Синтаксис Markdown: заголовки, списки, ссылки, код, таблицы

Markdown — это облегченный язык разметки: вы пишете обычный текст и добавляете несколько служебных символов (#, *, -, []()), а конвертер превращает его в оформленный HTML. Файл остается читаемым как есть, без предпросмотра. Ниже — синтаксис по элементам с примерами, разница между стандартом CommonMark и диалектом GitHub Flavored Markdown и когда Markdown уместнее прямого HTML.

Ключевое отличие от текстового процессора вроде Word: там оформление хранится в бинарном формате и не видно в исходнике. В Markdown разметка — это часть самого текста, поэтому файл .md открывается в любом редакторе и хорошо ложится в систему контроля версий.

Как устроена разметка

Markdown работает построчно и по абзацам. Пустая строка разделяет абзацы, а служебные символы в начале строки или вокруг слова задают форматирование. Один лишний или пропущенный символ меняет результат, поэтому синтаксис стоит запомнить точно.

Дальше во всех примерах показан именно исходный текст Markdown (то, что вы печатаете), а не результат его рендеринга. Это сделано намеренно: так видно сами символы разметки.

# Заголовок статьи

Обычный абзац с **жирным** и *курсивным* словом.

- первый пункт
- второй пункт

[ссылка на Otus](https://otus.ru)

Шпаргалка по синтаксису

Заголовки

Заголовок задается символами решетки (#) в начале строки. Число решеток — это уровень: одна для H1, две для H2 и так до шести. После решеток обязателен пробел.

# Раздел первого уровня
## Подраздел
### Пункт подраздела

Разумная практика — один H1 на документ (обычно заголовок страницы), остальное — H2 и ниже. Это упрощает навигацию и построение оглавления.

Акценты: курсив и полужирный

Для выделения используются звездочки или подчеркивания. Одинарные дают курсив, двойные — полужирный, тройные — и то и другое сразу.

*курсив* и _тоже курсив_
**полужирный** и __тоже полужирный__
***полужирный курсив***

Важная граница: в базовом Markdown нет разметки для подчеркивания текста. ***текст*** дает полужирный курсив, а не подчеркивание. Если нужно именно подчеркивание, вставляют HTML-тег <u>, и то не везде он разрешен.

Списки

Маркированный список — это строки, начатые с -, * или + и пробела. Нумерованный — строки вида 1., 2. и так далее. Номера конвертер часто пересчитывает сам, так что можно писать хоть все единицами.

- яблоко
- груша
- слива

1. установить редактор
2. открыть файл
3. сохранить как .md

Вложенность делается отступом (обычно 2-4 пробела или таб) перед дочерним пунктом. Так собирают многоуровневые и смешанные списки.

- фрукты
  - яблоко
  - груша
- овощи
  1. морковь
  2. лук

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

Ссылка записывается как текст в квадратных скобках и адрес в круглых, идущих сразу за ними. Картинка — то же самое, но с восклицательным знаком впереди; текст в скобках становится атрибутом alt.

[курсы Otus](https://otus.ru)
![схема архитектуры](images/arch.png)

Адрес может быть внешним (https://...) или относительным путем к файлу в репозитории. Alt-текст у картинки указывать желательно: его читают скринридеры и он показывается, если изображение не загрузилось.

Код: инлайн и блоки

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

Многострочный блок кода оформляют тремя обратными кавычками (fenced-блок) до и после. После открывающих кавычек можно указать язык — тогда подсветка синтаксиса будет корректной.

Запусти команду `npm install`, потом:

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

print(greet("мир"))  # Привет, мир
```

Тот же блок можно задать отступом в четыре пробела вместо кавычек, но fenced-вариант с указанием языка читается лучше и поддерживает подсветку.

Цитаты

Цитата оформляется знаком > в начале строки. Цитаты можно вкладывать друг в друга, добавляя вторую стрелку, и совмещать с другими элементами — списками, заголовками.

> Это цитата.
> Ее вторая строка.
>
> > А это вложенная цитата.

Горизонтальный разделитель

Три и более одинаковых символа -, * или _ на отдельной строке дают горизонтальную линию, которая делит документ на части.

Текст до разделителя.

***

Текст после разделителя.

Есть нюанс: если строка с --- идет сразу под текстом без пустой строки между ними, некоторые парсеры трактуют текст выше как заголовок (альтернативный синтаксис заголовка). Чтобы получить именно линию, оставляйте пустую строку над ---.

Экранирование символов

Если звездочка, решетка или другой служебный символ нужен как обычный текст, перед ним ставят обратный слеш (\). Тогда конвертер не применит форматирование.

\*это не курсив, а звездочки\*
1\. это не список, а точка после единицы

CommonMark и GitHub Flavored Markdown

У Markdown нет одного официального стандарта на все случаи. Исторически было много несовместимых реализаций, поэтому появился CommonMark — строгая спецификация базового синтаксиса (заголовки, списки, ссылки, код, цитаты, акценты).

GitHub Flavored Markdown (GFM) — это надстройка над CommonMark. Он добавляет то, чего в базовом стандарте нет: таблицы, списки задач, зачеркивание и автоссылки. Именно GFM используют GitHub, GitLab и многие движки документации.

Таблицы (GFM)

Таблица собирается из вертикальных черт | для столбцов и строки-разделителя из дефисов. Двоеточия в разделителе задают выравнивание столбца.

| Элемент | Символ | Диалект |
| --- | :---: | ---: |
| Таблица | \| | GFM |
| Заголовок | # | CommonMark |

Списки задач (GFM)

Список задач — это маркированный список, где вместо обычного маркера стоит [ ] для невыполненного пункта и [x] для выполненного. Платформы вроде GitHub рисуют их как интерактивные чекбоксы.

- [x] написать черновик
- [ ] вычитать текст
- [ ] опубликовать

Зачеркивание (GFM)

Зачеркнутый текст заключают в двойные тильды. В чистом CommonMark этого нет, символы отобразятся как есть.

~~устаревший пункт~~

Markdown или HTML: что выбрать

Markdown осознанно покрывает частые случаи форматирования и не претендует на сложную верстку. Если нужен точный контроль над отступами, стилями, колонками — это задача HTML и CSS, а не Markdown.

Многие парсеры разрешают вставлять HTML-теги прямо в Markdown-документ. Это удобно как запасной вариант: базовое оформление пишем на Markdown, а редкие сложные фрагменты — тегами. Поддержка встроенного HTML зависит от площадки: например, на GitHub часть тегов и атрибутов вырезается из соображений безопасности.

Выводы

• Markdown — облегченный язык разметки: текст остается читаемым, а несколько символов задают оформление и превращаются в HTML.
• Базовый набор (заголовки #, акценты */**, списки, ссылки []( ), код в обратных кавычках, цитаты >, разделитель ---) описан спецификацией CommonMark.
• Таблицы, списки задач, зачеркивание и автоссылки — это расширения GFM, а не часть базового стандарта.
• В Markdown нет подчеркивания и сложной верстки; для этого используют HTML и CSS, которые часто можно встроить прямо в документ.
• Основные сферы применения — README и документация проектов, заметки, сообщения в мессенджерах и чатах.

Где применяется / связь с практикой

Markdown — рабочий инструмент почти любого, кто пишет для веба и разработки. На нем оформляют файл README и документацию в репозиториях, ведут базы знаний и заметки, готовят черновики статей, форматируют сообщения в чатах и трекерах задач. Понимать разницу между Markdown, HTML и CSS полезно, потому что итоговая страница все равно рендерится в HTML и оформляется стилями.

FAQ

Какое расширение у файлов Markdown?
Чаще всего .md, реже .markdown. Это обычный текстовый файл в кодировке UTF-8, поэтому открывается в любом редакторе.

Одинаково ли Markdown выглядит на всех площадках?
Нет. Базовый синтаксис по CommonMark ведет себя предсказуемо, а расширения (таблицы, чекбоксы, эмодзи-коды) зависят от диалекта и движка. Перед публикацией стоит проверить результат именно на целевой площадке.

Можно ли смешивать Markdown и HTML в одном файле?
Во многих парсерах да: HTML-теги вставляются прямо в текст. Но набор разрешенных тегов ограничен площадкой, часть из них вырезается ради безопасности.