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

Колоссальная экономия токенов: В отличие от XML или HTML, где каждый тег требует закрытия (Текст), Markdown использует компактные одиночные маркеры или переносы строк.
Семантическая однозначность: Символы #, -, > дают модели четкое понимание логической структуры документа без избыточного синтаксического шума.
Естественность для потокового вывода (Streaming): Генерация текста по токенам без незакрытых громоздких тегов позволяет интерфейсам мгновенно отображать верстку в реальном времени.
Нативный контроль версий в Git: Документы .md представляют собой обычный текст, благодаря чему изменения отслеживаются через построчный git diff.

Примечание

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

2. Иерархия заголовков и навигационная структура документов

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

Иерархия уровней заголовков в 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	Результат отображения
Жирный (Bold)	`важный термин` или `__термин__`	важный термин
Курсив (Italic)	`акцент` или `_акцент_`	акцент
Жирный курсив	`*критическое действие*`	критическое действие
Зачеркивание (Strikethrough)	`~~устаревший параметр~~`	~~устаревший параметр~~
Инлайн-код	`apiKey`	`apiKey`

Практические правила типографики

Выделение внутри слова: Для форматирования части слова всегда используйте звездочки (A*cat*meow), так как нижнее подчеркивание внутри слов часто игнорируется парсерами во избежание конфликтов со snake_case переменными (user_auth_token).
Перенос строки внутри абзаца: Чтобы вставить принудительный перенос строки ( ) без создания нового абзаца, поставьте два пробела в конце строки или используйте тег  .
Скрытые комментарии: Для служебных пометок, невидимых при рендеринге, используйте 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/badge.webp)](https://example.com)` ### Обязательное percent-encoding кодирование спецсимволов в URL Если URL содержит пробелы, круглые скобки или кириллицу, прямая вставка разорвет синтаксис ссылки Markdown. Такие символы необходимо заменять на процентные коды: ![Правильное кодирование пробелов и круглых скобок в URL-ссылках](/api/guides-media/automation/markdown-format-guide-for-ai/images/markdown-format-guide-for-ai-extra-03.webp) ```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})`; }

Важно

Правило строгой изоляции промптов: Любые системные инструкции, промпты или шаблоны правил (.cursorrules, CLAUDE.md), содержащие символы заголовков (#, ##), обязаны быть обернуты в огороженный блок кода с явным указанием языка (например, markdown или text). Иначе внутренние заголовки промпта попадут в общее оглавление (TOC) страницы и разрушат структуру статьи.

7. Цитаты, коллауты и горизонтальные разделители

Цитаты начинаются с символа > в начале строки и служат для акцентирования внимания на ключевых выводах.

Стандартные и вложенные цитаты

markdown

> Цитата первого уровня. > > > Вложенная цитата второго уровня.

Современные блоки оповещений GitHub (Callout-блоки)

Платформы документации поддерживают стилизованные информационные карточки:

markdown

> [!NOTE] > Справочная информация или контекст. > [!TIP] > Совет по оптимизации, производительности или лучшим практикам. > [!IMPORTANT] > Критически важная информация, обязательная к соблюдению. > [!WARNING] > Предостережение о возможных сбоях или потере данных.

Горизонтальные разделители

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

markdown

Текст предыдущего раздела. --- Текст следующего раздела после линии.

8. Экранирование спецсимволов и встроенный HTML

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

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

Специальные символы Markdown, доступные для экранирования

Таблица экранируемых символов

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

Безопасное использование HTML

Если стандартных возможностей Markdown недостаточно, можно использовать HTML с учетом ограничений:

Тег   для принудительного переноса строк в таблицах.
Тег  для подчеркнутого текста.
Блочные теги (<div>, <table>) отделяются пустыми строками, а синтаксис 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-текстом.