Markdown: разметка для README, заметок и документации

Markdown придумали, чтобы текст с разметкой оставался читаемым и без отрисовки. Сегодня на нём пишут README, документацию, заметки, задачи и комментарии в Forgejo, GitLab и GitHub. Основа описана в спецификации CommonMark, а большинство площадок добавляет к ней расширения GitHub Flavored Markdown (GFM): таблицы, списки задач, зачёркивание и автоссылки.

Заголовки и абзацы

# Заголовок первого уровня
## Второй уровень
### Третий

Абзацы разделяются пустой строкой.
Перевод строки внутри абзаца при отрисовке превращается в пробел.

Чтобы сделать жёсткий перенос, поставьте в конце строки обратную косую черту\
или два пробела.

Альтернативный синтаксис заголовков — подчеркнуть строку знаками = или -. Он встречается в старых README, но с решётками удобнее.

Выделение текста

Подчёркивания внутри слов не считаются разметкой: snake_case_name останется как есть. Звёздочки внутри слов работают, поэтому для выделения части слова используйте их.

Списки

- пункт
- ещё пункт
  - вложенный: отступ на ширину маркера родителя
  - второй вложенный

1. Первый шаг
2. Второй шаг
   Продолжение пункта, выровненное по тексту.
3. Третий

- [x] сделанная задача (GFM)
- [ ] несделанная

Нумерованный список начинается с числа первого пункта, остальные номера отрисовщик пересчитает сам. Поэтому можно писать 1. у каждого пункта, и при перестановке ничего не придётся перенумеровывать.

Ссылки и картинки

[Текст ссылки](/docs/install/)
[Ссылка с подсказкой](/docs/install/ "Подсказка при наведении")
[Раздел этой страницы](#установка)
<mail@example.com>

![Схема сборки](images/build.svg)

[Справочная ссылка][инструкция], а адрес указан ниже.

[инструкция]: /docs/install/

Справочные ссылки удобны в длинных текстах: адреса собираются в конце документа и не мешают читать абзацы. Якоря на заголовки в GFM строятся автоматически: строчные буквы, пробелы заменены дефисами, знаки препинания убраны.

Код

Короткий фрагмент оборачивают в одиночные обратные кавычки, как npm install в этом абзаце. Если внутри фрагмента есть обратная кавычка, его оборачивают в двойные кавычки с пробелами по краям.

Блок кода — три обратные кавычки до и после, а после открывающих можно указать язык для подсветки:

```python
def greet(name: str) -> str:
    return f"Привет, {name}!"
```

```diff
- timeout = 30
+ timeout = 60
```

Если внутри блока нужно показать сами три кавычки, ограждайте его тильдами ~~~ или четырьмя кавычками. Старый способ — отступ в четыре пробела — тоже работает, но язык у такого блока не укажешь.

Таблицы

| Команда      | Что делает          | По умолчанию |
|:-------------|:-------------------:|-------------:|
| `build`      | собирает проект     |          нет |
| `test`       | запускает тесты     |           да |
| `a \| b`     | вертикальная черта  |              |

Двоеточие в строке-разделителе задаёт выравнивание: слева, по центру, справа. Выравнивать сами столбцы пробелами не обязательно, это только для удобства чтения исходника. Внутри ячейки нельзя сделать список или блок кода, а вертикальную черту нужно экранировать.

Цитаты, линии и сноски

> Цитата. Может быть многострочной,
> и внутри работает остальная разметка.
>
> > Вложенная цитата.

---

Утверждение со сноской.[^1]

[^1]: Текст сноски окажется внизу страницы.

Горизонтальная линия — три и больше дефиса, звёздочки или подчёркивания на отдельной строке. Осторожно: три дефиса сразу под строкой текста превращают её в заголовок второго уровня.

Многие площадки поддерживают и выделенные врезки:

> [!NOTE]
> Полезная информация.

> [!WARNING]
> Об этом стоит знать заранее.

HTML внутри Markdown

Там, где синтаксиса не хватает, можно вставить HTML: раскрывающийся блок, клавиши, перенос внутри таблицы.

<details>
<summary>Полный лог сборки</summary>

```text
...длинный вывод...
```

</details>

Нажмите <kbd>Ctrl</kbd>+<kbd>C</kbd>, чтобы остановить.

Пустые строки вокруг Markdown-содержимого внутри HTML-блока обязательны, иначе оно отрисуется как текст. Площадки вырезают опасные теги и атрибуты: <script>, style, обработчики событий.

Где разметка отличается

Если документ должен одинаково выглядеть везде, держитесь CommonMark и таблиц. Всё остальное проверяйте там, где документ будут читать.

Полезные мелочи

• Проверить, как изменился документ, удобно сравнением текстов или git diff --word-diff.
• Для единообразия есть линтеры: markdownlint ловит пропущенные пустые строки, разные маркеры списков и длинные строки.
• Одно предложение на строку в исходнике — приём для документации в git: диффы становятся точнее, а при отрисовке абзац всё равно склеится.
• Pandoc переводит Markdown в HTML, PDF, DOCX и обратно: pandoc README.md -o README.pdf.