# Формат 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 / ИИ-агент
(Точное чтение семантики)"]
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 | Эквивалент HTML | Назначение |
| :--- | :--- | :--- | :--- |
| **Уровень 1** | `# Заголовок` | `` | Название всей страницы (строго 1 на документ) |
| **Уровень 2** | `## Заголовок` | `` | Основные тематические разделы статьи |
| **Уровень 3** | `### Заголовок` | `` | Подразделы, шаги алгоритмов, отдельные утилиты |
| **Уровень 4** | `#### Заголовок` | `` | Технические параметры, пояснения |
| **Уровень 5** | `##### Заголовок` | `` | Мелкие служебные сноски |
| **Уровень 6** | `###### Заголовок` | `` | Микрозаголовки в спецификациях |
### Обязательный пробел после решетки
По спецификации CommonMark между символами решетки и текстом заголовка **обязан** стоять одинарный пробел. Без пробела современные парсеры воспримут строку как обычный хештег или неформатированный текст.
> [!WARNING]
> Никогда не используйте символ `#` для заголовка первого уровня в теле статьи, если заголовок уже объявлен в метаданных (frontmatter). На веб-странице должен присутствовать ровно один тег ``.
---
## 3. Оформление текста: жирный шрифт, курсив, зачеркивание и спецсимволы
Инлайновые маркеры позволяют автору акцентировать внимание читателя на ключевых терминах.
| Стиль оформления | Синтаксис Markdown | Результат отображения |
| :--- | :--- | :--- |
| **Жирный (Bold)** | `**важный термин**` или `__термин__` | **важный термин** |
| **Курсив (Italic)** | `*акцент*` или `_акцент_` | *акцент* |
| **Жирный курсив** | `***критическое действие***` | ***критическое действие*** |
| **Зачеркивание (Strikethrough)** | `~~устаревший параметр~~` | ~~устаревший параметр~~ |
| **Инлайн-код** | `` `apiKey` `` | `apiKey` |
### Практические правила типографики
- **Выделение внутри слова:** Для форматирования части слова всегда используйте звездочки (`A*cat*meow`), так как нижнее подчеркивание внутри слов часто игнорируется парсерами во избежание конфликтов со snake_case переменными (`user_auth_token`).
- **Перенос строки внутри абзаца:** Чтобы вставить принудительный перенос строки (`
`) без создания нового абзаца, поставьте два пробела в конце строки или используйте тег `
`.
- **Скрытые комментарии:** Для служебных пометок, невидимых при рендеринге, используйте HTML-комментарии: ``.
---
## 4. Списки и вложенные структуры: нумерованные, маркированные и чек-боксы
Списки позволяют аккуратно организовать последовательности действий и перечни параметров.
### Маркированные, нумерованные и интерактивные списки
:::tabs
@tab Маркированный список
```markdown
- Первичный аудит
- Проектирование архитектуры
- Вложенный подпункт (отступ 2 или 4 пробела)
- Второе требование
- Финальный релиз
```
@tab Нумерованный список
```markdown
1. Клонируйте репозиторий
2. Установите зависимости
3. Запустите dev-сервер
```
@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)`
### Обязательное percent-encoding кодирование спецсимволов в URL
Если URL содержит пробелы, круглые скобки или кириллицу, прямая вставка разорвет синтаксис ссылки Markdown. Такие символы необходимо заменять на процентные коды:
```markdown
[Статья из Википедии](https://ru.wikipedia.org/wiki/Компьютер_%28значения%29)
[Статья из Википедии](https://ru.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 (Callout-блоки)
Платформы документации поддерживают стилизованные информационные карточки:
```markdown
> [!NOTE]
> Справочная информация или контекст.
> [!TIP]
> Совет по оптимизации, производительности или лучшим практикам.
> [!IMPORTANT]
> Критически важная информация, обязательная к соблюдению.
> [!WARNING]
> Предостережение о возможных сбоях или потере данных.
```
### Горизонтальные разделители
Три дефиса (`---`), звездочки (`***`) или подчеркивания (`___`) на отдельной строке создают тематическую разделительную линию:
```markdown
Текст предыдущего раздела.
---
Текст следующего раздела после линии.
```
---
## 8. Экранирование спецсимволов и встроенный HTML
Если служебный символ Markdown требуется отобразить как обычный печатный знак, перед ним ставится обратный слеш (`\`).
### Таблица экранируемых символов
| Символ | Название | Пример экранирования | Результат |
| :--- | :--- | :--- | :--- |
| `\` | Обратный слеш (Backslash) | `\\` | \ |
| `` ` `` | Обратная кавычка (Backtick) | `` \` `` | ` |
| `*` | Звездочка (Asterisk) | `\*не курсив\*` | \*не курсив\* |
| `_` | Подчеркивание (Underscore) | `\_не жирный\_` | \_не жирный\_ |
| `#` | Решетка (Hash) | `\# Не заголовок` | \# Не заголовок |
| `[` `]` | Квадратные скобки | `\[Не ссылка\]` | \[Не ссылка\] |
| `!` | Восклицательный знак | `\!Не картинка` | \!Не картинка |
### Безопасное использование HTML
Если стандартных возможностей Markdown недостаточно, можно использовать HTML с учетом ограничений:
- Тег `
` для принудительного переноса строк в таблицах.
- Тег `` для подчеркнутого текста.
- Блочные теги (``, `
`) отделяются пустыми строками, а синтаксис 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: Построение AST в памяти (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. Введение").
3. Все фрагменты кода оборачивай в тройные бэктики с указанием языка (typescript, bash, json, mermaid).
4. Таблицы оформляй по стандарту GFM с явным выравниванием колонок.
5. Для важных предупреждений используй callout-блоки (> [!NOTE], > [!WARNING]).
6. Ссылки с пробелами или скобками должны содержать percent-encoded URL (%20, %28, %29).
Выведи чистый, готовый к публикации Markdown-документ без лишних комментариев.
```
### Чек-лист проверки качества Markdown-документа
- [ ] В теле статьи отсутствует символ `#` (H1 формируется из frontmatter).
- [ ] Все разделы верхнего уровня пронумерованы последовательно (`## 1.`, `## 2.`).
- [ ] После каждого символа `#` стоит пробел.
- [ ] Все промпты и примеры кода изолированы внутри блоков ` ``` `.
- [ ] Спецсимволы в URL ссылок закодированы в формате percent-encoding.
- [ ] Таблицы оформлены по стандарту GFM без разорванных разделителей.
- [ ] Все иллюстрации снабжены осмысленным alt-текстом.