Markdown: формат, который стоит знать при работе с ИИ

Что такое Markdown и зачем он нужен

Markdown — лёгкий язык разметки текста: пишете обычными символами, но получаете структуру (заголовки, списки, ссылки, выделения), если документ потом отрендерить. Ключевое отличие от разметки вроде HTML — текст остаётся читаемым и полезным даже без рендеринга. Строка ## Заголовок понятна человеку и в виде голого текста, и после превращения в настоящий заголовок.

Формат легко переносится между инструментами: заметки, чаты с ИИ, README на GitHub, техническая документация — везде один и тот же синтаксис. Отдельный плюс для тех, кто работает с git: обычный текстовый файл в Markdown прекрасно показывает построчный diff при изменениях — в отличие от .docx, где любая правка превращается в нечитаемую бинарную кашу.

Заголовки

От одной решётки до шести — уровни H1–H6, чем больше решёток, тем ниже уровень заголовка:

# Заголовок первого уровня (H1)
## Заголовок второго уровня (H2)
### Заголовок третьего уровня (H3)
#### Четвёртый уровень (H4)
##### Пятый уровень (H5)
###### Шестой уровень (H6)

Есть и альтернативный синтаксис — но только для первых двух уровней: подчеркнуть строку заголовка знаком = снизу даёт H1, знаком - — H2:

Заголовок первого уровня
=========================

Заголовок второго уровня
-------------------------

Абзацы и переносы строк

Между абзацами обязательно нужна пустая строка. Простой перенос строки внутри абзаца рендерится как обычный пробел — строки слипаются в один абзац, что часто удивляет новичков:

Первая строка текста.
Вторая строка — рендерер склеит её с первой через пробел.

А это уже отдельный абзац, потому что перед ним пустая строка.

Если действительно нужен перенос строки внутри одного абзаца (не новый абзац) — есть два способа: поставить два пробела в конце строки перед переносом, либо вставить сырой HTML-тег <br>.

Форматирование текста

Базовые выделения — звёздочки или подчёркивания вокруг текста:

**жирный текст**
*курсив*
***жирный курсив***
~~зачёркнутый текст~~

Получится: жирный текст, курсив, жирный курсив, зачёркнутый текст. А вот подчёркивание и цвет текста сам Markdown нативно не поддерживает — это можно сделать только вставкой сырого HTML прямо внутри markdown-документа (например <u>текст</u>).

Комментарии

Строки вида <!-- текст --> не попадают в отрендеренный документ — удобно оставлять заметки для себя или для соавторов прямо в исходнике, не засоряя финальный вид документа.

Списки

Нумерованный список — рендерер сам расставляет номера по порядку, даже если в исходнике цифры идут не по порядку. Поэтому многие просто пишут 1. перед каждым пунктом, не считая вручную:

1. Первый пункт
1. Второй пункт
1. Третий пункт

Маркированный список — дефис, звёздочка или плюс перед строкой (любой из трёх):

- Первый пункт
- Второй пункт
  - Вложенный пункт (отступ)
- Третий пункт

Вложенность задаётся отступом. Если внутрь пункта списка нужно добавить что-то ещё — абзац текста, блок кода — используется отступ в 4 пробела от начала строки маркера.

Ссылки

Базовая форма — текст в квадратных скобках, адрес в круглых:

[текст ссылки](https://example.com)
[текст со всплывающей подсказкой](https://example.com "Подсказка при наведении")
<https://example.com>

Последний вариант — автоссылка: URL сам становится ссылкой без отдельного текста. Если один и тот же адрес используется в документе многократно, удобен reference-style синтаксис — ссылка в тексте оформляется по идентификатору, а сам адрес выносится отдельно (например, в конец документа):

Смотрите [документацию][docs] по теме.

[docs]: https://example.com/docs

Если в самом URL встречаются пробелы или скобки — их нужно экранировать процентной кодировкой: пробел — %20, открывающая скобка — %28, закрывающая — %29.

Изображения

Тот же синтаксис, что у ссылок, только с восклицательным знаком в начале:

![Описание изображения](https://example.com/image.png)

Текст в квадратных скобках — это alt-текст, он не просто подпись: важен для доступности (его читают программы для незрячих) и для SEO/GEO — поисковики и ИИ-краулеры, которые не «видят» картинку, ориентируются именно на него. Если нужно сделать изображение кликабельным — картинку оборачивают в синтаксис ссылки:

[![Описание](https://example.com/image.png)](https://example.com)

Код

Инлайн-код (внутри строки текста) оформляется одинарными бэктиками: `код`. Если внутри самого кода уже есть бэктик — снаружи ставят двойные, чтобы не спутать границы:

Используйте функцию `sum()`.
Чтобы показать сам символ бэктика в коде: `` `код` ``

Блок кода можно оформить отступом в 4 пробела от начала строки, но удобнее — огородить его тройными бэктиками (fenced-блок) и указать язык сразу после них, тогда рендерер подсветит синтаксис:

```python
def hello():
    print("Привет")
```

Цитаты

Знак > перед строкой превращает её в цитату:

Это цитата. Может занимать несколько абзацев — просто ставьте > перед каждой строкой, включая пустые между абзацами.

Цитаты можно вкладывать друг в друга двойным знаком >>, а внутри самой цитаты работают другие элементы Markdown — списки, жирный текст и так далее:

> Первый уровень цитаты
>
> > Вложенная цитата
>
> Список внутри цитаты:
> - **важный** пункт
> - обычный пункт

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

Три и более символов *, - или _ подряд на отдельной строке рисуют разделительную линию — любой из трёх вариантов работает одинаково:

***
---
___

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

Если нужно показать управляющий символ Markdown буквально, а не как разметку — перед ним ставится обратный слэш \. Например, чтобы звёздочки вокруг слова не превратились в курсив:

\*это не курсив\*

HTML внутри Markdown

Во многих markdown-документах можно вставлять сырой HTML напрямую — но полагаться на это стоит с осторожностью: в чатах с ИИ и некоторых рендерерах (в том числе в интерфейсах вроде Хелпера) HTML-теги могут не сработать и просто отобразятся как текст. Если HTML всё же используется — блочные теги (<div>, <table> и подобные) нужно отделять пустыми строками от остального markdown-текста, иначе рендерер может их не распознать правильно. Важный нюанс в обратную сторону: сам синтаксис Markdown не работает внутри блочных HTML-тегов — звёздочки и решётки там останутся обычным текстом.