Что такое Markdown
Markdown - это простой текстовый формат разметки: вы пишете обычный текст и расставляете знаки вроде #, * и -, а программа превращает их в заголовки, выделение и списки. Файлы Markdown имеют расширение .md и открываются любым текстовым редактором. Формат придумали, чтобы исходник читался глазами даже без преобразования.
Где он применяется: файлы README в репозиториях, документация проектов, описания задач и пулл-реквестов, заметки в Obsidian и других редакторах, ячейки текста в тетрадях Jupyter. Если вы работаете с кодом, Markdown вам понадобится быстро. Например, оформить описание проекта на GitHub без него не получится.
У формата есть несколько диалектов. Оригинальный синтаксис описал Джон Грубер, затем появился стандарт CommonMark, который однозначно определяет правила. GitHub Flavored Markdown (GFM) - расширение CommonMark с таблицами, чек-листами, зачёркиванием и автоссылками. Большинство примеров ниже работают и в CommonMark, и в GFM, а отдельные расширения помечены.
Шпаргалка: как написать и что получится
В таблице собраны основные конструкции. В левом столбце - то, что нужно набрать, в правом - результат после обработки.
| Как написать | Что получится |
|---|---|
# Заголовок | Заголовок первого уровня (h1) |
## Заголовок | Заголовок второго уровня (h2), и так до шести решёток |
**текст** | жирный текст |
*текст* или _текст_ | курсив |
***текст*** | жирный курсив |
~~текст~~ | зачёркнутый текст (GFM) |
- пункт или * пункт | маркированный список |
1. пункт | нумерованный список |
[текст](https://example.com) | ссылка с подписью "текст" |
 | картинка с альтернативным текстом |
`код` | короткий фрагмент кода в строке |
> цитата | блок цитаты |
--- на отдельной строке | горизонтальная линия |
- [ ] задача и - [x] готово | чек-лист с флажками (GFM) |
Перед решёткой и после неё нужен пробел: #Заголовок без пробела в CommonMark заголовком не считается. Между блоками разного типа, например абзацем и списком, оставляйте пустую строку, иначе разные редакторы могут обработать текст по-разному.
Заголовки, абзацы и переносы строк
Количество решёток задаёт уровень заголовка. Для статьи обычно используется один заголовок первого уровня, дальше разделы второго и подразделы третьего.
# Название проекта
Короткое описание в одном абзаце.
## Установка
### Через pip
Абзацы отделяются пустой строкой. Если просто нажать Enter внутри абзаца, большинство обработчиков склеит две строки в одну. Чтобы получить перенос внутри абзаца, закончите строку двумя пробелами или обратной косой чертой. В комментариях и описаниях задач на GitHub достаточно одного Enter, но в файлах репозитория работает правило с пробелами или косой чертой.
Выделение текста и списки
Жирный текст получается двойными звёздочками или двойными подчёркиваниями, курсив - одинарными. Внутри слова надёжнее звёздочки: подчёркивания в середине слов во многих обработчиках не работают.
Для списков допустимы дефис, плюс или звёздочка, но внутри одного списка выбирайте один знак. Вложенность задаётся отступом из двух или четырёх пробелов.
- Фрукты
- Яблоки
- Бананы
- Овощи
1. Скачать архив
2. Распаковать
3. Запустить установку
Нумерованный список можно писать цифрами подряд: Markdown сам нумерует пункты по порядку, начиная с первого числа. Поэтому при вставке нового пункта не нужно перенумеровывать остальные, хотя многие авторы пишут всё равно по порядку, чтобы исходник читался.
Ссылки и картинки
Ссылка записывается как текст в квадратных скобках и адрес в круглых. Картинка - то же самое с восклицательным знаком впереди. Вместо относительного пути можно указать полный адрес.
[Документация Python](https://docs.python.org/3/)
[Подсказка при наведении](https://example.com "Заголовок ссылки")

<https://example.com>
Ссылка со ссылочным стилем: [читать][doc]
[doc]: https://docs.python.org/3/
Адрес в угловых скобках превращается в ссылку с самим адресом в качестве текста. Ссылочный стиль удобен, когда один адрес повторяется несколько раз: определение [doc]: ... пишется отдельной строкой в любом месте документа. На GitHub обычный адрес вида https://... превращается в ссылку и без скобок.
Для картинок всегда заполняйте альтернативный текст в квадратных скобках: он показывается, если файл не загрузился, и читается программами экрана.
Код в Markdown
Короткий фрагмент оборачивается в одинарные обратные кавычки (backtick), блок кода - в три. После трёх кавычек в начале блока можно указать язык: так включится подсветка синтаксиса. Этот способ называется fenced code block, он есть в CommonMark и GFM.
Запустите `python main.py` в терминале.
```python
def hello(name):
return f"Привет, {name}!"
print(hello("мир"))
```
Название языка после кавычек - python, js, bash, json, sql - зависит от того, какую подсветку поддерживает конкретная программа. Если нужно показать в блоке саму тройную кавычку, оборачивайте его в четыре обратные кавычки. Исходный отступ из четырёх пробелов тоже даёт блок кода, но такой способ считается устаревшим: язык подсветки при нём не указать.
Если вы пишете Markdown в редакторе кода, пригодится настройка VS Code: в нём есть встроенный предпросмотр, он открывается сочетанием Ctrl+Shift+V.
Таблицы в Markdown
Таблицы появились в расширении GFM и теперь поддерживаются почти везде, но не в самой базовой версии Markdown. Столбцы разделяются вертикальной чертой, а вторая строка из дефисов отделяет заголовок от данных.
| Язык | Тип | Год |
|:-----------|:----------:|----:|
| Python | Динамический | 1991 |
| Go | Статический | 2009 |
Двоеточия во второй строке задают выравнивание: слева от дефисов - по левому краю, с обеих сторон - по центру, справа - по правому. Ровно выравнивать пробелами столбцы в исходнике не обязательно, это нужно только для удобства чтения. Если в ячейке нужна сама вертикальная черта, экранируйте её обратной косой чертой.
Переносов строк внутри ячейки в таблице нет: для этого используют тег <br>, если обработчик разрешает HTML. Составлять большие таблицы вручную неудобно, лучше пользоваться редактором с помощью или генератором.
Чек-листы, цитаты и дополнительные возможности GFM
Чек-листы пишутся как обычный список с квадратными скобками. Пробел внутри скобок означает невыполненную задачу, буква x - выполненную. На GitHub такие флажки можно переключать мышью в описании задачи.
- [x] Написать README
- [ ] Добавить примеры
- [ ] Проверить ссылки
> Цитата занимает отдельный блок.
> Её можно продолжать на следующей строке.
Цитата начинается со знака >, вложенные цитаты - с двух таких знаков. Внутри цитаты работает остальная разметка: списки, выделение, код.
Ещё несколько возможностей GFM, которые встречаются в документации. Сноски в стиле [^1] с определением ниже. Автоматические ссылки на задачи и пользователей: #123 и @username. Блоки предупреждений в описаниях на GitHub, например > [!NOTE] и > [!WARNING] с текстом на следующих строках. Это возможности конкретной платформы: в других редакторах они могут отображаться как обычная цитата.
Экранирование и HTML
Если нужно вывести символ, который Markdown воспринимает как разметку, поставьте перед ним обратную косую черту: \*не курсив\*, \# не заголовок. Экранировать можно звёздочки, подчёркивания, решётки, скобки, кавычки-бэктики и другие служебные знаки.
Многие обработчики позволяют вставлять обычный HTML, если разметки не хватает, например для картинки определённого размера или для сворачиваемого блока. Но возможности разных платформ отличаются, и часть тегов на них отфильтровывается: GitHub, например, удаляет скрипты и стили. Поэтому HTML внутри Markdown лучше использовать редко и проверять в предпросмотре.
Самая частая ошибка новичков - не оставить пустую строку перед списком, таблицей или блоком кода. В итоге всё склеивается в один абзац, и разметка не срабатывает. Поставьте пустую строку между блоками и проверьте текст в предпросмотре.

Чем писать и открывать Markdown
Писать можно в любом текстовом редакторе. Но удобнее программы с живым предпросмотром, где слева исходник, а справа готовый вид. Варианты бывают такие.
| Способ | Для чего удобен |
|---|---|
| VS Code, PyCharm и другие среды | README и документация рядом с кодом, предпросмотр в отдельной вкладке |
| Онлайн-редакторы Markdown | быстро проверить разметку без установки |
| Редакторы заметок | личные записи, ссылки между заметками |
| Jupyter Notebook | текстовые ячейки рядом с кодом |
| Репозиторий на GitHub | файл README.md отображается автоматически на странице проекта |
В тетрадях Jupyter Notebook ячейка с типом Markdown использует тот же синтаксис, поэтому заметки с заголовками и формулами оформляются точно так же.
Преобразование Markdown в HTML, PDF и Word
Из Markdown можно получить другие форматы. Для документов, PDF и Word популярна универсальная программа pandoc: она читает .md и сохраняет в нужный формат по расширению выходного файла.
pandoc README.md -o README.html
pandoc README.md -o README.docx
Первая команда создаёт HTML-страницу, вторая - документ Word. Для PDF pandoc дополнительно требует установленный механизм вёрстки, например LaTeX, поэтому проще открыть файл в редакторе с предпросмотром и распечатать в PDF.
Из Python Markdown превращается в HTML с помощью пакета markdown. Установите его командой python -m pip install markdown.
import markdown
text = """# Привет
Это **Markdown**.
| a | b |
|---|---|
| 1 | 2 |
"""
html_text = markdown.markdown(text, extensions=["tables", "fenced_code"])
print(html_text)
Расширение tables включает поддержку таблиц, а fenced_code - блоки кода в тройных кавычках. Программа выведет HTML с тегами h1, p, strong и table. Если вам нужно сохранить результат в файл, помните про кодировку: открывайте файл с параметром encoding="utf-8", подробнее об этом в статье про кодировку UTF-8.
Если Markdown лежит в репозитории, изменения в нём отслеживаются так же, как в коде. Основные команды для этого собраны в шпаргалке по командам Git.
