Markdown

Markdown — облегчённый язык разметки, в котором форматирование задаётся простыми символами: # для заголовков, * для выделения, - для списков. Главная идея — текст в Markdown должен оставаться легко читаемым как есть, без превращения в HTML, и при этом однозначно в него преобразовываться. Автор языка Джон Грубер ориентировался на то, как люди и раньше оформляли обычные письма.^[1]

Markdown стал стандартом де-факто для README-файлов, документации, вики, заметок, комментариев на GitHub и форумах, а также основным форматом ответов языковых моделей.

История

Джон Грубер опубликовал описание синтаксиса и конвертер на Perl в 2004 году; в разработке участвовал Аарон Шварц. Исходное описание было неформальным и оставляло много неоднозначностей, поэтому десятки реализаций разбирали один и тот же текст по-разному.

В 2014 году группа разработчиков во главе с Джоном Макфарлейном (автором Pandoc) выпустила CommonMark — строгую спецификацию с сотнями тестовых примеров.^[2] GitHub в 2017 году описал свой диалект GitHub Flavored Markdown (GFM) как надмножество CommonMark с таблицами, списками задач, зачёркиванием и автоссылками.^[3] В 2016 году для Markdown был зарегистрирован MIME-тип text/markdown (RFC 7763).^[4]

Синтаксис

# Заголовок первого уровня
## Заголовок второго уровня

Обычный абзац с *курсивом*, **жирным** и `кодом в строке`.
Ссылка: [документация](https://example.com), изображение: ![схема](diagram.png).

- пункт списка
- ещё пункт
  - вложенный пункт

1. нумерованный
2. список

> Цитата

```python
print("блок кода с подсветкой")
```

| Команда | Действие |
|---|---|
| `ls` | список файлов |

- [x] выполненная задача (GFM)
- [ ] невыполненная задача

Пустая строка разделяет абзацы, а внутрь Markdown можно вставлять обычный HTML, если синтаксиса не хватает.

Диалекты и расширения

Популярные расширения: диаграммы Mermaid в блоках кода, блоки-предупреждения (> [!NOTE]), метаданные во front matter для генераторов статических сайтов. Из-за разнообразия диалектов документ, написанный для одного инструмента, может отображаться иначе в другом — переносимее всего придерживаться CommonMark с таблицами GFM.

Где используется

• Репозитории. README.md, CHANGELOG.md, CONTRIBUTING.md отображаются на GitHub и GitLab автоматически.
• Документация. MkDocs, Docusaurus, Hugo и другие генераторы собирают сайты из Markdown-файлов.
• Заметки. Obsidian, Logseq, Joplin хранят заметки в обычных .md-файлах.
• Научные и инженерные тексты. Ячейки Jupyter-ноутбуков, R Markdown, Quarto.
• Конвертация. Pandoc превращает Markdown в PDF, DOCX, EPUB, презентации и обратно.^[5]

Markdown и языковые модели

Языковые модели обучались на огромном количестве Markdown-текстов и сами отвечают в этом формате. Для подачи документации в модель Markdown удобнее HTML: в нём нет вёрстки, скриптов и навигации, он экономит токены и сохраняет структуру — заголовки, списки, таблицы, блоки кода. На этом построен стандарт llms.txt, а сайты документации публикуют Markdown-версии страниц рядом с HTML. Подробнее — в статье Markdown как формат для LLM.

Хорошие практики

• Один заголовок первого уровня на документ, иерархия без пропусков уровней.
• У блоков кода указывать язык — для подсветки и для понимания моделями.
• Не полагаться на одиночный перевод строки — в CommonMark он не создаёт новую строку.
• Проверять стиль линтером (markdownlint) и единообразно оформлять списки и таблицы.

См. также

• Markdown как формат для LLM
• llms.txt
• Статический сайт и генераторы (SSG)
• HTML
• tldr-pages

Источники

1. John Gruber — Markdown (Daring Fireball, 2004)
2. CommonMark Spec
3. GitHub Flavored Markdown Spec
4. RFC 7763 — The text/markdown Media Type
5. Pandoc User's Guide