# Markdown

> Облегчённый язык разметки, созданный Джоном Грубером в 2004 году, — читаемый как обычный текст и легко преобразуемый в HTML; стандарт де-факто для README, документации и ответов языковых моделей.

Источник: https://llmdocs.ru/wiki/markdown/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Тип**: облегчённый язык разметки
- **Авторы**: Джон Грубер, при участии Аарона Шварца
- **Появился**: 2004
- **Спецификации**: CommonMark (с 2014), GitHub Flavored Markdown
- **MIME-тип**: text/markdown (RFC 7763)
- **Расширения файлов**: .md, .markdown
- **Конвертеры**: Pandoc, markdown-it, Python-Markdown, cmark
**Markdown** — облегчённый язык разметки, в котором форматирование задаётся простыми символами: `#` для заголовков, `*` для выделения, `-` для списков. Главная идея — текст в Markdown должен оставаться легко читаемым как есть, без превращения в [HTML](https://llmdocs.ru/wiki/html.md), и при этом однозначно в него преобразовываться. Автор языка Джон Грубер ориентировался на то, как люди и раньше оформляли обычные письма.[1]

Markdown стал стандартом де-факто для README-файлов, документации, вики, заметок, комментариев на [GitHub](https://llmdocs.ru/wiki/github.md) и форумах, а также основным форматом ответов языковых моделей.

## История

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

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

## Синтаксис

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

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

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

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

> Цитата

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

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

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

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

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

| Возможность | CommonMark | GFM | Другие |
|---|---|---|---|
| Заголовки, списки, ссылки, код | да | да | да |
| Таблицы | нет | да | большинство |
| Списки задач, зачёркивание | нет | да | многие |
| Сноски | нет | да | Pandoc, MkDocs |
| Формулы (`$...$`) | нет | да | Pandoc, Obsidian, Jupyter |
| Front matter (YAML в начале) | нет | нет | генераторы сайтов |
| Вики-ссылки `[[...]]` | нет | нет | Obsidian, вики-движки |

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

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

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

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

Языковые модели обучались на огромном количестве Markdown-текстов и сами отвечают в этом формате. Для подачи документации в модель Markdown удобнее HTML: в нём нет вёрстки, скриптов и навигации, он экономит [токены](https://llmdocs.ru/wiki/tokenization.md) и сохраняет структуру — заголовки, списки, таблицы, блоки кода. На этом построен стандарт [llms.txt](https://llmdocs.ru/wiki/llms-txt.md), а сайты документации публикуют Markdown-версии страниц рядом с HTML. Подробнее — в статье [Markdown как формат для LLM](https://llmdocs.ru/wiki/markdown-for-llm.md).

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

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

## См. также

- [Markdown как формат для LLM](https://llmdocs.ru/wiki/markdown-for-llm.md)
- [llms.txt](https://llmdocs.ru/wiki/llms-txt.md)
- [Статический сайт и генераторы (SSG)](https://llmdocs.ru/wiki/static-site-generators.md)
- [HTML](https://llmdocs.ru/wiki/html.md)
- [tldr-pages](https://llmdocs.ru/wiki/tldr-pages.md)

## Источники

1. [John Gruber — Markdown (Daring Fireball, 2004)](https://daringfireball.net/projects/markdown/)
2. [CommonMark Spec](https://spec.commonmark.org/)
3. [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
4. [RFC 7763 — The text/markdown Media Type](https://www.rfc-editor.org/rfc/rfc7763)
5. [Pandoc User's Guide](https://pandoc.org/MANUAL.html)