Большинство документов начинаются как обычный текстовый файл с несколькими звёздочками и решётками. Обычно этот файл написан на Markdown. Это не единственный способ писать для веба, но он стал стандартом для README, трекеров задач, чат-ботов и статических сайтов, потому что исходник можно читать ещё до рендеринга.
Этот пост — быстрый практический туториал. Предполагается, что у вас есть десять минут и текстовый редактор. Устанавливать ничего не нужно.
Что такое Markdown
Markdown — это лёгкий язык разметки. Джон Грубер опубликовал оригинальную спецификацию в 2004 году с одной целью: создать формат, который хорошо выглядит в виде обычного текста и чисто конвертируется в HTML. С тех пор он стал входным форматом для GitHub, Obsidian, Notion, многих генераторов статических сайтов и большинства выводов крупных языковых моделей.
Главная идея проста. Структуру обозначают знаками препинания вместо тегов:
# Это заголовок
Это абзац.
- Это элемент списка
- Это другой элемент
Парсер превращает это в HTML. Разные парсеры поддерживают разные расширения, поэтому стандарты имеют значение.
Стандарты Markdown важны
У Markdown нет единого официального стандарта. Оригинальная спецификация Грубера оставляла пробелы, которые разные инструменты заполнили несовместимыми способами. Если вы напишете таблицу в одном приложении и вставите в другое, она может сломаться. Нужно понимать, на какой диалект вы ориентируетесь.
- CommonMark. Строгая, хорошо протестированная спецификация, начатая в 2014 году. Точно определяет базовый синтаксис. Если важна переносимость, пишите на CommonMark.
- GitHub Flavored Markdown (GFM). Добавляет таблицы, списки задач, зачёркивание, ограждённые блоки кода и автоссылки. Именно это используется в README и комментариях GitHub.
- Pandoc Markdown. Добавляет цитаты, сноски, списки определений, нижние и верхние индексы, математику. Распространён в академическом письме.
- Obsidian / Quarto / MDX. Добавляют вики-ссылки, callout, исполняемые ячейки кода или встроенные компоненты. Мощно, но плохо переносится.
Для повседневной работы самый безопасный выбор — GFM. Для длинных документов, которые могут мигрировать между инструментами, лучше CommonMark плюс задокументированный набор расширений.
Основы Markdown
Заголовки
Используйте от одного до шести знаков решётки. Один — самый крупный.
# Заголовок 1
## Заголовок 2
### Заголовок 3
Абзацы и переносы строк
Абзацы разделяйте пустой строкой. Для принудительного переноса строки в конце строки поставьте два пробела или обратный слеш.
Это первый абзац.
Это второй абзац.
Выделение
_курсив_ или _курсив_
**жирный** или **жирный**
**_жирный курсив_**
~~зачёркнутый~~ (только GFM)
Списки
Маркированные списки используют -, * или +:
- Пункт один
- Пункт два
- Вложенный пункт
Нумерованные списки используют цифры:
1. Шаг один
2. Шаг два
3. Шаг три
Цифры не обязаны быть правильными. Markdown перенумерует их при рендеринге. Всё равно лучше использовать последовательные числа, чтобы исходник оставался читаемым.
Ссылки и изображения
[Текст ссылки](https://example.com)
[Ссылка с заголовком](https://example.com "Заголовок")
Для внутренних ссылок используйте относительные пути:
[Конвертер Markdown в PDF](/tools/markdown-to-pdf)
Код
Встроенный код окружается одним обратным апострофом: `console.log("hi")`.
Блоки кода — тремя обратными апострофами:
```python
def hello():
return "hello"
```
После открывающих обратных апострофов укажите идентификатор языка, чтобы подсветка синтаксиса сработала.
## Популярные приёмы и примеры
### Цитаты
```markdown
> Это цитата.
> Она может занимать несколько строк.
Цитаты можно вкладывать друг в друга:
> Внешняя цитата
>
> > Вложенная цитата
Горизонтальные линии
---
Используйте три или более дефиса, звёздочки или подчёркивания на отдельной строке.
Списки задач
GFM поддерживает чекбоксы:
- [x] Написать черновик
- [ ] Проверить таблицы
- [ ] Опубликовать пост
В HTML они рендерятся как отключённые чекбоксы. Не заменяйте ими настоящие поля форм.
Экранирование символов
Чтобы символ Markdown отобразился как есть, поставьте перед ним обратный слеш:
\*не курсив\*
\# не заголовок
Продвинутые приёмы и примеры
Таблицы
Таблицы — это расширение GFM, а не часть оригинальной спецификации Markdown.
| Возможность | CommonMark | GFM |
| ------------ | ---------- | --- |
| Таблицы | Нет | Да |
| Списки задач | Нет | Да |
Выравнивание необязательно:
| Слева | По центру | Справа |
| :---- | :-------: | -----: |
| A | B | C |
Держите таблицы простыми. Вложенные таблицы, объединение строк и столбцов не являются стандартом и часто ломаются.
Сноски
Pandoc и некоторые GFM-парсеры поддерживают сноски:
Здесь утверждение.[^1]
[^1]: Это текст сноски.
Если сноски нужны в отрендеренном PDF, используйте конвертер с поддержкой синтаксиса Pandoc или вставьте их вручную.
Математика
Pandoc и многие современные редакторы поддерживают математику LaTeX:
Встроенная формула: $E = mc^2$
Блочная формула:
$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$
Рендеринг математики зависит от парсера и формата вывода. Для HTML обычно нужны MathJax или KaTeX. Для PDF-конвертеров часто требуется LaTeX-бэкенд.
Списки определений
Ещё одно расширение Pandoc:
Термин
: Определение термина.
Другой термин
: Другое определение.
HTML внутри Markdown
Когда Markdown не хватает, можно перейти на HTML:
<p style="color: red;">Этот текст красный.</p>
Это полезно для вёрстки, встроенного видео или атрибутов, которые Markdown не поддерживает. Но это убивает переносимость, поэтому используйте умеренно.
Когда конвертировать Markdown
Markdown отлично подходит для написания текста и контроля версий. Он плох для финальных документов, которые должны выглядеть одинаково везде. Поэтому существуют конвертеры.
Если у вас есть черновик в Markdown, который нужно превратить в PDF для отправки, используйте конвертер Markdown в PDF. Он работает в браузере, поэтому файл не покидает ваш компьютер.
Если у вас есть PDF и нужен редактируемый Markdown, используйте конвертер PDF в Markdown. Он извлекает заголовки, списки и абзацы без загрузки на сервер.
Шпаргалка по Markdown
| Элемент | Синтаксис | Пример вывода |
|---|---|---|
| Заголовок 1 | # H1 | H1 |
| Заголовок 2 | ## H2 | H2 |
| Заголовок 3 | ### H3 | H3 |
| Жирный | **bold** | bold |
| Курсив | *italic* | italic |
| Зачёркнутый | ~~text~~ | |
| Встроенный код | `code` | code |
| Ссылка | [text](url) | text |
| Изображение |  | изображение |
| Цитата | > quote | цитата |
| Маркированный список | - item | элемент списка |
| Нумерованный список | 1. item | элемент списка |
| Горизонтальная линия | --- | линия |
| Блок кода | ```lang | блок с подсветкой |
| Список задач | - [ ] task | чекбокс |
| Таблица | | a | b | | таблица |
Распечатайте эту таблицу и прикрепите её рядом с монитором — редко придётся снова искать синтаксис Markdown.
Итог
Markdown вознаграждает сдержанность. Для 90% того, что вы пишете, хватит базового синтаксиса. Таблицы, сноски и HTML доставайте только тогда, когда документ действительно в них нуждается. Если придерживаться CommonMark или GFM, файлы будут свободно перемещаться между редакторами, платформами и конвертерами без сюрпризов.
