Skip to main content
Всі гайди
Зміст гайду

Зміст гайду

Час на вивчення: 15 хв
#automation#markdown#format#guide#ai#claude#docs
Середній15 хв

Формат Markdown: повний посібник для роботи з ШІ та автоматизації

Вичерпний практичний посібник з синтаксису Markdown для AI-розробки: CommonMark, ієрархія заголовків, GFM-таблиці, екранування, системні промпти та файли CLAUDE.md.

Опубліковано:

1. Що таке Markdown: філософія, CommonMark та чому це рідна мова ШІ

Markdown — це полегшена мова розмітки тексту, створена Джоном Грубером у 2004 році з простою метою: писати структурований текст, який залишається максимально читабельним у сирому вигляді та легко конвертується в валідний HTML. Сучасний еталон формату стандартизовано в специфікації CommonMark та розширено стандартом GitHub Flavored Markdown (GFM).

У взаємодії зі штучним інтелектом (ChatGPT, Claude Code, Gemini, локальні моделі Ollama) саме Markdown є головною мовою спілкування.

mermaid
flowchart LR A["Сирий текст Markdown<br><i>(Мінімальна вага, чистий UTF-8)</i>"] --> B["LLM / AI-агент<br><i>(Точне розуміння семантики)</i>"] B --> C{"Парсинг та рендеринг"} C --> D["HTML / Вебсайти<br><i>(Заголовки, списки, таблиці)</i>"] C --> E["DOCX / PDF звіти<br><i>(Конвертація через Pandoc)</i>"] C --> F["Системний контекст<br><i>(CLAUDE.md, .cursorrules)</i>"]

Чому великі мовні моделі «думають» у Markdown

  1. Ідеальна економія токенів: На відміну від XML чи HTML, де кожен тег вимагає відкриття й закриття (<p>Текст</p>), у Markdown використовуються лише мінімальні службові маркери або звичайні переноси рядків.
  2. Семантична однозначність: Символи #, -, > та кодові бектіки не перевантажують контекстне вікно, даючи моделі чітку карту ієрархії думок.
  3. Природність для потокового виводу (Streaming): Генерація тексту слово за словом без складних незакритих тегів дозволяє рендерити форматування на льоту в інтерфейсі чату.
  4. Контроль версій у Git: Файли .md є звичайними текстовими файлами, тому будь-які зміни в базі знань чи документації легко відстежуються через git diff.
Примітка

Форматування в Markdown ділиться на два рівні: блокові елементи (заголовки, списки, цитати, таблиці, блоки коду) та інлайнові елементи (жирний шрифт, курсив, посилання, інлайн-код). Блокові елементи обов'язково відокремлюються порожнім рядком.

2. Ієрархія заголовків та навігаційна структура документів

Заголовки задають кістяк документа і формують зміст (Table of Contents). У Markdown рівні заголовків позначаються символом решітки (#) на початку рядка — від одного до шести.

Ієрархія рівнів заголовків у Markdown та відповідні HTML-теги ЗбільшитиІєрархія рівнів заголовків у Markdown та відповідні HTML-тегиІєрархія рівнів заголовків у Markdown та відповідні HTML-теги
Рівень заголовкаСинтаксис MarkdownЕквівалент HTMLТипове застосування
Рівень 1# Заголовок<h1>Назва всієї статті або документа (лише 1 на сторінку)
Рівень 2## Заголовок<h2>Головні розділи та ключові модулі теми
Рівень 3### Заголовок<h3>Підрозділи, кроки інструкцій, окремі інструменти
Рівень 4#### Заголовок<h4>Деталізація підпунктів, параметри, примітки
Рівень 5##### Заголовок<h5>Дрібні службові виноски
Рівень 6###### Заголовок<h6>Мікрозаголовки специфікацій

Критичне правило пробілу після решітки

Відповідно до стандарту CommonMark, між символом решітки та текстом заголовка обов'язково має бути одинарний пробіл. Якщо пробіл відсутній, більшість сучасних парсерів розцінять запис як звичайний хештег або сирий текст.

Порівняння правильного та неправильного написання заголовків ЗбільшитиПорівняння правильного та неправильного написання заголовківПорівняння правильного та неправильного написання заголовків
Увага

Ніколи не використовуйте символ # для заголовка першого рівня всередині тіла статті, якщо заголовок уже задано у метаданих (frontmatter). На сторінці має бути рівно один семантичний тег <h1>.

3. Оформлення тексту: жирний шрифт, курсив, закреслення та спецсимволи

Інлайнове виділення допомагає акцентувати увагу на ключових термінах та поняттях.

Синтаксис виділення тексту курсивом у Markdown ЗбільшитиСинтаксис виділення тексту курсивом у MarkdownСинтаксис виділення тексту курсивом у Markdown
Стиль виділенняСинтаксис MarkdownРезультат відображення
Жирний (Bold)**важливий термін** або __термін__важливий термін
Курсив (Italic)*акцент* або _акцент_акцент
Жирний курсив***критична дія***критична дія
Закреслення (Strikethrough)~~застаріла версія~~застаріла версія
Інлайн-код`apiKey`apiKey

Практичні нюанси типографіки

  • Виділення всередині слова: Якщо потрібно виділити частину слова, завжди використовуйте зірочки (A*cat*meow), оскільки нижнє підкреслення всередині слів деякі процесори ігнорують, сприймаючи як частину ідентифікатора змінної (user_profile_id).
  • Перенесення рядка без нового абзацу: Щоб додати перенесення рядка (<br>) всередині одного абзацу, поставте два пробіли в кінці рядка або скористайтеся тегом <br>.
  • Коментарі: Для нотаток, які не повинні рендеритися на фінальній сторінці, використовуйте синтаксис HTML-коментарів: <!-- Це внутрішній коментар -->.

4. Списки та вкладені структури: нумеровані, марковані та чек-бокси

Списки структурують покрокові алгоритми та набори параметрів.

Марковані та нумеровані списки

Додаткові блоки всередині списків

Щоб вставити абзац, цитату чи блок коду всередину пункту списку без розриву загальної нумерації, зробіть відступ у 4 пробіли перед кожним дочірнім рядком:

markdown
1. Запустіть процес збірки проєкту: ```bash ```bash npm run build
terminal
``` > [!NOTE] > Переконайтеся, що змінні оточення у файлі `.env` налаштовані правильно перед запуском.

2. Перевірте вихідний каталог dist/.

terminal
--- ## 5. Посилання, зображення та правильне кодування URL Синтаксис посилань та медіафайлів будується на поєднанні квадратних і круглих дужок. ### Базові конструкції посилань - **Звичайне інлайнове посилання:** `[Документація Anthropic](https://docs.anthropic.com)` - **Посилання зі спливаючою підказкою (title):** `[Claude Code](https://claude.ai "Офіційний сайт")` - **Автопосилання:** `<https://github.com>` або `<support@example.com>` - **Зображення:** `![Опис зображення для доступності](/images/diagram.webp "Підказка")` - **Клікабельне зображення-посилання:** `[![Alt-текст](/images/btn.webp)](https://example.com)` ### Правильне кодування спецсимволів в URL Якщо URL-адреса містить пробіли, круглі дужки чи кирилицю, пряма вставка зламає синтаксис Markdown-посилання. Такі символи слід обов'язково замінювати на процентні коди (URL percent-encoding): ![Правильне кодування пробілів та круглих дужок у URL посиланнях](/api/guides-media/automation/markdown-format-guide-for-ai/images/markdown-format-guide-for-ai-extra-03.webp) ```markdown <!-- Правильно: пробіл замінено на %20, дужки на %28 та %29 --> [Стаття з Вікіпедії](https://uk.wikipedia.org/wiki/Комп%27ютер_%28значення%29) <!-- Неправильно: розриває синтаксис круглих дужок Markdown --> [Стаття з Вікіпедії](https://uk.wikipedia.org/wiki/Комп'ютер_(значення))

6. Інлайн-код, кодові блоки та підсвічування синтаксису

Код та конфігурації вимагають моноширинного шрифту та захисту від інтерпретації внутрішніх символів.

Інлайн-код проти Fenced кодових блоків

  • Інлайн-код: одинарні зворотні лапки (бектіки): git status.
  • Екранування бектіка всередині інлайн-коду: обгортання подвійними бектіками: `npm test`.
  • Fenced-блоки коду: потрійні бектіки з обов'язковим зазначенням ідентифікатора мови.
typescript
interface UserProfile { id: string; username: string; isActive: boolean; } export function formatUser(user: UserProfile): string { return `@${user.username} (ID: ${user.id})`; }
Важливо

Суворе правило ізоляції промптів: Будь-які системні промпти чи правила асистентів (.cursorrules, CLAUDE.md), які містять власні символи заголовків (#, ##), обов'язково мають бути загорнуті у відокремлений кодовий блок із зазначенням мови (наприклад, markdown або text). Якщо залишити їх без кодового блоку в тілі тексту, внутрішні заголовки промпту потраплять у зміст (TOC) статті та зруйнують навігацію сторінки.

7. Цитати, коллаути та горизонтальні розділювачі

Цитати створюються символом > на початку рядка і використовуються для виділення думок, важливих застережень або цитування тексту.

Стандартні цитати та багаторівнева вкладеність

markdown
> Це цитата першого рівня. > > > Це вкладена цитата другого рівня всередині попередньої.

Сучасні GitHub Alerts (Callout-блоки)

Сучасні платформи документації підтримують стандартизовані виділені блоки з кольоровими іконками:

markdown
> [!NOTE] > Корисна довідкова інформація або контекст для розуміння. > [!TIP] > Порада щодо оптимізації, підвищення ефективності чи найкраща практика. > [!IMPORTANT] > Критично важлива інформація, обов'язкова до виконання. > [!WARNING] > Застереження про потенційні помилки, збої або втрату даних.

Горизонтальні розділювачі

Три або більше дефіси (---), зірочки (***) або підкреслення (___) на окремому рядку створюють горизонтальну лінію:

markdown
Текст попереднього розділу. --- Текст наступного розділу після розділювача.

8. Екранування спецсимволів та вбудований HTML

Коли потрібно вивести символ синтаксису Markdown як звичайний друкований знак, перед ним ставлять зворотний слеш (\).

Спеціальні символи синтаксису Markdown, які можна екранувати зворотним слешем ЗбільшитиСпеціальні символи синтаксису Markdown, які можна екранувати зворотним слешемСпеціальні символи синтаксису Markdown, які можна екранувати зворотним слешем

Список символів для екранування

СимволНазва знакаПриклад екрануванняРезультат рендеру
\Зворотний слеш (Backslash)\\\
`Зворотна лапка (Backtick)\``
*Зірочка (Asterisk)\*не курсив\**не курсив*
_Підкреслення (Underscore)\_не жирний\__не жирний_
#Решітка (Hash)\# Не заголовок# Не заголовок
[ ]Квадратні дужки\[Не посилання\][Не посилання]
!Окличний знак\!Не картинка!Не картинка

Безпечне використання HTML

Якщо стандартного Markdown недостатньо, можна скористатися тегами HTML, проте варто пам'ятати про обмеження:

  • Тег <br> для примусового перенесення рядків у таблицях.
  • Тег <u> для підкресленого тексту.
  • Блочні теги (<div>, <table>) повинні відділятися від коду Markdown порожніми рядками, а всередині них розмітка Markdown не працює.

9. Таблиці GitHub Flavored Markdown (GFM) та Mermaid-діаграми

Таблиці дозволяють порівнювати характеристики, параметри та конфігурації.

Синтаксис GFM-таблиць із вирівнюванням

markdown
| Параметр | Опис функціональності | Значення за замовчуванням | Статус | | :--- | :--- | :---: | ---: | | `apiKey` | Секретний ключ авторизації | `null` | Обов'язковий | | `timeout` | Максимальний час очікування | `5000` | Опціональний | | `retries` | Кількість повторних спроб | `3` | Рекомендовано |
  • :--- — вирівнювання стовпця за лівим краєм.
  • :---: — вирівнювання по центру.
  • ---: — вирівнювання за правим краєм (ідеально для цін і чисел).

Візуалізація архітектури через Mermaid

Замість важких растрових скриншотів, сучасні розробники використовують вбудовані текстові діаграми Mermaid:

mermaid
sequenceDiagram autonumber actor User as Розробник participant AI as Claude Code / GPT-4o participant FS as Файлова система User->>AI: Запит на генерацію документації AI->>AI: Побудова структури в пам'яті (CommonMark) AI->>FS: Запис файлу README.md FS-->>User: Готовий структурований артефакт

10. Markdown в AI-агентах: CLAUDE.md, System Prompts та чек-лист валідації

В епоху автономних AI-агентів (Claude Code, Cursor, Windsurf, Devin) Markdown став головною мовою передачі інженерного контексту.

Файли інструкцій проєкту (CLAUDE.md / .cursorrules)

Агенти читають кореневий файл CLAUDE.md перед кожним запитом. Якщо він оформлений якісно, модель безпомилково дотримується архітектури проєкту:

markdown
Інженерні стандарти проєкту =========================== 1. Команди збірки та тестування: - Збірка: npm run build - Запуск юніт-тестів: npm test - Лінтер: npm run lint 2. Архітектурні правила: - Використовувати тільки Server Components за замовчуванням. - Усі типи зберігати в каталозі src/types/. - Жодних any у коді TypeScript.

Майстер-промпт для генерації бездоганного Markdown

markdown
Дій як провідний технічний редактор та експерт із документації. Створи технічну документацію за специфікацією CommonMark / GFM. Тема: [Вкажіть тему, наприклад: Архітектура мікросервісу автентифікації] Вимоги до розмітки: 1. Заголовки строго від ## 1. до ## N. (Жодного # у тілі документа). 2. Завжди став одинарний пробіл після знаків решітки (наприклад, "## 1. Вступ", а не "##1. Вступ"). 3. Усі фрагменти коду оформлюй у потрійні бектіки із зазначенням мови (typescript, bash, json, mermaid). 4. Порівняльні матриці подавай у валідних GFM-таблицях із вирівнюванням колонок. 5. Для важливих застережень використовуй callout-блоки (> [!NOTE], > [!WARNING]). 6. Посилання з пробілами або дужками мають містити percent-encoded URL (%20, %28, %29). Виведи чистий, готовий до публікації Markdown-документ.

Чек-лист перевірки якості Markdown-документа

  • У тілі статті відсутній тег # (H1 генерується виключно із заголовка сторінки).
  • Усі розділи верхнього рівня пронумеровані послідовно (## 1., ## 2.).
  • Після символів решітки # обов'язково стоїть пробіл.
  • Усі промпти, конфігурації та кодові приклади загорнуті у відповідні блоки ```.
  • Спецсимволи в посиланнях закодовані у форматі percent-encoding.
  • Таблиці оформлені за стандартом GFM без пошкоджених розділювачів.
  • Усі зображення мають змістовний alt-текст для доступності.
Цей гайд повністю безкоштовний. Якщо він зекономив вам вечір — ви можете підтримати розвиток проєкту.
Підтримати автора