# Формат 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
(Мінімальна вага, чистий UTF-8)"] --> B["LLM / AI-агент
(Точне розуміння семантики)"]
B --> C{"Парсинг та рендеринг"}
C --> D["HTML / Вебсайти
(Заголовки, списки, таблиці)"]
C --> E["DOCX / PDF звіти
(Конвертація через Pandoc)"]
C --> F["Системний контекст
(CLAUDE.md, .cursorrules)"]
```
### Чому великі мовні моделі «думають» у Markdown
1. **Ідеальна економія токенів:** На відміну від XML чи HTML, де кожен тег вимагає відкриття й закриття (`Текст
`), у Markdown використовуються лише мінімальні службові маркери або звичайні переноси рядків.
2. **Семантична однозначність:** Символи `#`, `-`, `>` та кодові бектіки не перевантажують контекстне вікно, даючи моделі чітку карту ієрархії думок.
3. **Природність для потокового виводу (Streaming):** Генерація тексту слово за словом без складних незакритих тегів дозволяє рендерити форматування на льоту в інтерфейсі чату.
4. **Контроль версій у Git:** Файли `.md` є звичайними текстовими файлами, тому будь-які зміни в базі знань чи документації легко відстежуються через `git diff`.
> [!NOTE]
> Форматування в Markdown ділиться на два рівні: **блокові елементи** (заголовки, списки, цитати, таблиці, блоки коду) та **інлайнові елементи** (жирний шрифт, курсив, посилання, інлайн-код). Блокові елементи обов'язково відокремлюються порожнім рядком.
---
## 2. Ієрархія заголовків та навігаційна структура документів
Заголовки задають кістяк документа і формують зміст (Table of Contents). У Markdown рівні заголовків позначаються символом решітки (`#`) на початку рядка — від одного до шести.
| Рівень заголовка | Синтаксис Markdown | Еквівалент HTML | Типове застосування |
| :--- | :--- | :--- | :--- |
| **Рівень 1** | `# Заголовок` | `` | Назва всієї статті або документа (лише 1 на сторінку) |
| **Рівень 2** | `## Заголовок` | `` | Головні розділи та ключові модулі теми |
| **Рівень 3** | `### Заголовок` | `` | Підрозділи, кроки інструкцій, окремі інструменти |
| **Рівень 4** | `#### Заголовок` | `` | Деталізація підпунктів, параметри, примітки |
| **Рівень 5** | `##### Заголовок` | `` | Дрібні службові виноски |
| **Рівень 6** | `###### Заголовок` | `` | Мікрозаголовки специфікацій |
### Критичне правило пробілу після решітки
Відповідно до стандарту CommonMark, між символом решітки та текстом заголовка **обов'язково** має бути одинарний пробіл. Якщо пробіл відсутній, більшість сучасних парсерів розцінять запис як звичайний хештег або сирий текст.
> [!WARNING]
> Ніколи не використовуйте символ `#` для заголовка першого рівня всередині тіла статті, якщо заголовок уже задано у метаданих (frontmatter). На сторінці має бути рівно один семантичний тег ``.
---
## 3. Оформлення тексту: жирний шрифт, курсив, закреслення та спецсимволи
Інлайнове виділення допомагає акцентувати увагу на ключових термінах та поняттях.
| Стиль виділення | Синтаксис Markdown | Результат відображення |
| :--- | :--- | :--- |
| **Жирний (Bold)** | `**важливий термін**` або `__термін__` | **важливий термін** |
| **Курсив (Italic)** | `*акцент*` або `_акцент_` | *акцент* |
| **Жирний курсив** | `***критична дія***` | ***критична дія*** |
| **Закреслення (Strikethrough)** | `~~застаріла версія~~` | ~~застаріла версія~~ |
| **Інлайн-код** | `` `apiKey` `` | `apiKey` |
### Практичні нюанси типографіки
- **Виділення всередині слова:** Якщо потрібно виділити частину слова, завжди використовуйте зірочки (`A*cat*meow`), оскільки нижнє підкреслення всередині слів деякі процесори ігнорують, сприймаючи як частину ідентифікатора змінної (`user_profile_id`).
- **Перенесення рядка без нового абзацу:** Щоб додати перенесення рядка (`
`) всередині одного абзацу, поставте два пробіли в кінці рядка або скористайтеся тегом `
`.
- **Коментарі:** Для нотаток, які не повинні рендеритися на фінальній сторінці, використовуйте синтаксис HTML-коментарів: ``.
---
## 4. Списки та вкладені структури: нумеровані, марковані та чек-бокси
Списки структурують покрокові алгоритми та набори параметрів.
### Марковані та нумеровані списки
:::tabs
@tab Маркований список
```markdown
- Перший пункт плану
- Другий пункт плану
- Вкладений підпункт (відступ 2 або 4 пробіли)
- Ще один вкладений підпункт
- Третій пункт плану
```
@tab Нумерований список
```markdown
1. Завантажте репозиторій
2. Встановіть залежності
3. Запустіть сервер розробки
```
@tab Інтерактивні чек-бокси (Task Lists)
```markdown
- [x] Створити файл конфігурації
- [x] Налаштувати підключення до бази даних
- [ ] Запустити інтеграційні тести
```
:::
### Додаткові блоки всередині списків
Щоб вставити абзац, цитату чи блок коду всередину пункту списку без розриву загальної нумерації, зробіть відступ у 4 пробіли перед кожним дочірнім рядком:
```markdown
1. Запустіть процес збірки проєкту:
```bash
npm run build
```
> [!NOTE]
> Переконайтеся, що змінні оточення у файлі `.env` налаштовані правильно перед запуском.
2. Перевірте вихідний каталог `dist/`.
```
---
## 5. Посилання, зображення та правильне кодування URL
Синтаксис посилань та медіафайлів будується на поєднанні квадратних і круглих дужок.
### Базові конструкції посилань
- **Звичайне інлайнове посилання:** `[Документація Anthropic](https://docs.anthropic.com)`
- **Посилання зі спливаючою підказкою (title):** `[Claude Code](https://claude.ai "Офіційний сайт")`
- **Автопосилання:** `` або ``
- **Зображення:** ``
- **Клікабельне зображення-посилання:** `[](https://example.com)`
### Правильне кодування спецсимволів в URL
Якщо URL-адреса містить пробіли, круглі дужки чи кирилицю, пряма вставка зламає синтаксис Markdown-посилання. Такі символи слід обов'язково замінювати на процентні коди (URL percent-encoding):
```markdown
[Стаття з Вікіпедії](https://uk.wikipedia.org/wiki/Комп%27ютер_%28значення%29)
[Стаття з Вікіпедії](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})`;
}
```
> [!IMPORTANT]
> **Суворе правило ізоляції промптів:** Будь-які системні промпти чи правила асистентів (`.cursorrules`, `CLAUDE.md`), які містять власні символи заголовків (`#`, `##`), **обов'язково** мають бути загорнуті у відокремлений кодовий блок із зазначенням мови (наприклад, markdown або text). Якщо залишити їх без кодового блоку в тілі тексту, внутрішні заголовки промпту потраплять у зміст (TOC) статті та зруйнують навігацію сторінки.
---
## 7. Цитати, коллаути та горизонтальні розділювачі
Цитати створюються символом `>` на початку рядка і використовуються для виділення думок, важливих застережень або цитування тексту.
### Стандартні цитати та багаторівнева вкладеність
```markdown
> Це цитата першого рівня.
>
> > Це вкладена цитата другого рівня всередині попередньої.
```
### Сучасні GitHub Alerts (Callout-блоки)
Сучасні платформи документації підтримують стандартизовані виділені блоки з кольоровими іконками:
```markdown
> [!NOTE]
> Корисна довідкова інформація або контекст для розуміння.
> [!TIP]
> Порада щодо оптимізації, підвищення ефективності чи найкраща практика.
> [!IMPORTANT]
> Критично важлива інформація, обов'язкова до виконання.
> [!WARNING]
> Застереження про потенційні помилки, збої або втрату даних.
```
### Горизонтальні розділювачі
Три або більше дефіси (`---`), зірочки (`***`) або підкреслення (`___`) на окремому рядку створюють горизонтальну лінію:
```markdown
Текст попереднього розділу.
---
Текст наступного розділу після розділювача.
```
---
## 8. Екранування спецсимволів та вбудований HTML
Коли потрібно вивести символ синтаксису Markdown як звичайний друкований знак, перед ним ставлять зворотний слеш (`\`).
### Список символів для екранування
| Символ | Назва знака | Приклад екранування | Результат рендеру |
| :--- | :--- | :--- | :--- |
| `\` | Зворотний слеш (Backslash) | `\\` | \ |
| `` ` `` | Зворотна лапка (Backtick) | `` \` `` | ` |
| `*` | Зірочка (Asterisk) | `\*не курсив\*` | \*не курсив\* |
| `_` | Підкреслення (Underscore) | `\_не жирний\_` | \_не жирний\_ |
| `#` | Решітка (Hash) | `\# Не заголовок` | \# Не заголовок |
| `[` `]` | Квадратні дужки | `\[Не посилання\]` | \[Не посилання\] |
| `!` | Окличний знак | `\!Не картинка` | \!Не картинка |
### Безпечне використання HTML
Якщо стандартного Markdown недостатньо, можна скористатися тегами HTML, проте варто пам'ятати про обмеження:
- Тег `
` для примусового перенесення рядків у таблицях.
- Тег `` для підкресленого тексту.
- Блочні теги (``, `
`) повинні відділятися від коду 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-текст для доступності.