Skip to content

Markdown Шпаргалка

Лёгкий язык разметки для форматированного текста.

01

Начало работы

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

Используйте # для заголовков (1-6 уровней). Альтернативный синтаксис: === для H1 и --- для H2. Абзацы разделяются пустой строкой. Markdown задуман читаемым как обычный текст.

markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

Переносы строк

Два пробела в конце строки или обратная косая создают жёсткий перенос (<br>). Без них одиночный перевод строки — мягкий перенос, строки склеиваются в один абзац. Всегда оставляйте пустую строку между абзацами.

markdown
First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

Комментарии

В Markdown нет официального синтаксиса комментариев, но HTML-комментарии (<!-- -->) работают в большинстве рендереров и скрыты в выводе. Приём [//]: # использует пустую ссылку для заметок. Комментарии всё равно видны в исходнике.

markdown
<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

Пробелы и отступы

Четыре ведущих пробела превращают текст в блок кода: остерегайтесь случайных отступов. Отступы важны для вложенных списков (2-4 пробела на уровень). Табуляция обычно считается 4 пробелами. Используйте пробелы последовательно, чтобы избежать проблем отображения в разных парсерах.

markdown
Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

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

Три и более дефиса, звёздочки или подчёркивания создают горизонтальную линию (<hr>). Дефисы распространены чаще всего. Пробелы между символами допустимы. Для ясности ставьте пустые строки вокруг линии. Не путайте --- (линию) с # (заголовком).

markdown
---

***

___

   * * *

Text above

---

Text below
02

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

Жирный (strong)

Двойные звёздочки или подчёркивания дают жирный текст (<strong>). Звёздочки предпочтительнее: подчёркивания не работают внутри слова (snake_case). Внутрь жирного можно вкладывать другие выделения. HTML-тег <strong> работает как запасной вариант.

markdown
**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

Курсив (em)

Одинарные звёздочки или подчёркивания дают курсив (<em>). Звёздочки работают внутри слова; подчёркивания внутри слова считаются буквальными (поэтому no_italic_here). Запасной вариант — <em>. Курсив нужен для смыслового выделения, а не просто оформления.

markdown
*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

Жирный + курсив

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

markdown
***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

Зачёркивание

Двойные тильды (~~) создают зачёркивание — часть GitHub Flavored Markdown, теперь широко поддерживается. HTML-теги <del> и <s> — эквивалентные запасные варианты. В стандартном (исходном) Markdown зачёркивания нет.

markdown
~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

Mark / выделение

Двойное равно (==) для выделения — расширение, поддерживаемое некоторыми парсерами (не в ядре GFM). HTML-тег <mark> работает везде. Используйте выделение редко, чтобы акцентировать ключевые термины: злоупотребление снижает эффект.

markdown
==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

Нижний и верхний индекс

Синтаксис тильды (нижний индекс) и каретки (верхний) (~ ~ и ^ ^) — расширения, которых нет в стандартном Markdown и GFM; поддерживаются Pandoc, R Markdown и немногими другими. Для универсальности используйте HTML <sub> и <sup> или символы Unicode.

markdown
H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions
03

Списки

Маркированные списки

Используйте -, * или + для элементов маркированного списка: выберите один и будьте последовательны (- чаще всего). Вложенные элементы с отступом 2-4 пробела. Смешение маркеров в одном списке может вызывать проблемы в некоторых парсерах. Один элемент на строку.

markdown
- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

Нумерованные списки

Нумерованные списки используют числа с точкой. Сами числа не обязаны идти подряд: Markdown перенумерует. Чтобы начать с конкретного числа, поставьте его первым (10. начинает с 10). Используйте 1. для всех элементов, чтобы нумерация была автоматической.

markdown
1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

Вложенные списки

Делайте отступ вложенных элементов 2-4 пробела (4 надёжнее для смешанных типов). На разных уровнях можно смешивать нумерованные и маркированные списки. Глубокая вложенность (3+ уровня) вредит читаемости — подумайте о переструктурировании. Держите отступы последовательными.

markdown
1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

Списки задач

Синтаксис списка задач (- [x] и - [ ]) — расширение GitHub Flavored Markdown. Флажок на GitHub/GitLab интерактивен. Работает и с нумерованными, и с маркированными списками. Отлично для README, трекеров задач и отслеживания прогресса.

markdown
- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

Плотные и разреженные списки

Если элементы разделены пустыми строками, список «разреженный» (каждый элемент обёрнут в <p>). Без пустых строк он «плотный» (без обёрток <p>). Это влияет на отступы в HTML. Добавляйте пустые строки осознанно, чтобы управлять обёрткой абзацев.

markdown
- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

Список с несколькими абзацами

Чтобы включить в элемент списка несколько абзацев или блочных элементов, отступите продолжение на 4 пробела (или выровняйте по содержимому маркера). Подблоки разделяются пустыми строками. Это необходимо для сложных списков, но легко ошибиться.

markdown
- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item
05

Изображения

Базовое изображение

Синтаксис изображения как у ссылки, но с префиксом !. Alt-текст обязателен для доступности: он описывает изображение для скринридеров и показывается при ошибке загрузки. Путь может быть относительным, абсолютным или URL. Заголовок необязателен.

markdown
![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

Изображение с alt-текстом

Alt-текст должен быть осмысленным и кратким: описывайте назначение изображения, а не просто «изображение». Для декоративных изображений допустим пустой alt (alt=''), чтобы скринридеры их пропустили. Никогда не пишите «картинка с» или «фото»: скринридер и так это объявит.

markdown
![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

Изображение-ссылка

Оберните изображение в ссылку, вложив синтаксис изображения в синтаксис ссылки: [![alt](img)](url). Часто для миниатюр, ведущих на полный размер, бейджей со статусом CI и логотипов со ссылкой на главную. Alt-текст описывайте по назначению ссылки, а не только изображения.

markdown
[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

Изображения по ссылкам

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

markdown
![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

Размеры изображений и figure

В стандартном Markdown нет синтаксиса размеров: используйте HTML <img> с атрибутами width/height. Процентные ширины дают адаптивность. Комбинация <figure> + <figcaption> даёт семантические подписи (HTML5). Некоторые расширения (Pandoc) поддерживают ![alt](img){width=300}.

markdown
<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>
06

Встроенный код и экранирование

Встроенный код

Заключайте встроенный код в одинарные обратные кавычки. Чтобы показать кавычки внутри кода, используйте двойные как разделитель (или больше). Встроенный код выводится моноширинным и не разбирается как Markdown. Отлично для имён файлов, команд и идентификаторов.

markdown
Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

Экранирование обратных кавычек

Чтобы включить обратную кавычку в код, используйте разделитель из большего числа кавычек, чем внутри: двойные вокруг одинарной. Вне кода обратную кавычку экранируют обратной косой. Закрывающий разделитель должен совпадать по длине с открывающим.

markdown
To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

Код и пробелы

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

markdown
`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

Экранирование обратной косой

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

markdown
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

Какие символы экранировать

Это экранируемые символы Markdown. Не все нужно экранировать везде: # важен только в начале строки, - в контексте списка и т. д. Сомневаетесь — экранируйте. Фигурные и круглые скобки обычно требуют экранирования только в особых контекстах (ссылки, строки шаблонов).

markdown
\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation
07

Блоки кода

Блоки кода с отступом

Отступ в 4 пробела (или табуляция) создаёт блок кода. У таких блоков нет подсветки синтаксиса и языковой метки. Их нельзя использовать внутри элементов списка (считается продолжением). Для нового контента предпочитайте ограждённые блоки: отступные устарели.

markdown
Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

Ограждённые блоки кода

Тройные обратные кавычки или тройные тильды создают ограждённый блок кода. Ограждения предпочтительнее отступов: они однозначны и поддерживают языковые подсказки. Тильды (~~~) удобны, когда в коде есть тройные обратные кавычки. Всегда закрывайте тем же числом символов.

markdown
```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

Подсветка синтаксиса

Добавьте идентификатор языка сразу после открывающего ограждения для подсветки (например, js, python). Большинство рендереров используют highlight.js или Prism. Частые псевдонимы: js, ts, py, rb, sh, json, html, css. Если язык неизвестен, опустите его для простого моноширинного текста.

markdown
```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

```python
def greet(name):
    print(f"Hello, {name}!")
```

```bash
echo "Hello, $USER"
```

Вложенные ограждения

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

markdown
Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

Код в списках

Ограждённые блоки внутри элементов списка нужно выровнять по тексту списка (обычно 3 пробела для списков -, 4 для 1.). Блокам с отступом внутри списков нужно 8 пробелов (4 за список + 4 за код). Правильное выравнивание — одна из самых сложных задач Markdown.

markdown
1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).
08

Блок-цитаты

Базовая блок-цитата

Символ > начинает блок-цитату. Можно ставить его в каждой строке или только в первой: большинство парсеров склеивают соседние строки. Блок-цитаты выводятся как сдвинутые стилизованные цитаты (<blockquote>). Используйте их для цитат, врезок и выделения фрагментов.

markdown
> This is a blockquote.
> It can span multiple lines.

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

Многострочная блок-цитата

Используйте пустые строки с > для разделения абзацев внутри цитаты (иначе они сольются). > на пустой строке держит цитату открытой. Без пустых строк между абзацами текст идёт одним абзацем. Всегда закрывайте обычной строкой.

markdown
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

Вложенные блок-цитаты

Несколько символов > создают вложенные цитаты (>> для двух уровней, >>> для трёх). Добавляйте пробелы для читаемости. Глубокая вложенность (3+ уровня) плохо читается и стилизуется — лучше упростить. Каждый уровень добавляет отступ в HTML.

markdown
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

Блок-цитаты с другими элементами

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

markdown
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

Блок-цитата с источником

В Markdown нет формального синтаксиса цитирования. Частые соглашения: автор с длинным тире на новой строке или HTML <blockquote> с <footer> и <cite> для семантических ссылок. Для академических цитат рассмотрите сноску с источником.

markdown
> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>
09

Таблицы

Базовая таблица

В таблицах вертикальные черты (|) разделяют колонки, дефисы отделяют заголовок. Строка заголовка обязательна. Черты по краям строк необязательны, но улучшают читаемость. Ширина колонок не важна: ячейки подстраиваются. Таблицы — расширение GitHub Flavored Markdown.

markdown
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

Выравнивание ячеек

Двоеточия в строке-разделителе задают выравнивание: :--- влево, :---: по центру, ---: вправо. Без двоеточий по умолчанию влево. Выравнивание применяется ко всей колонке и задаёт text-align в HTML. Полезно для числовых колонок (вправо) и заголовков (по центру).

markdown
| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

Таблица с форматированием

Ячейки могут содержать встроенный Markdown: жирный, курсив, код, ссылки, зачёркивание, эмодзи. Блочные элементы (заголовки, списки, блоки кода) внутри ячеек не работают: при необходимости используйте HTML. Держите содержимое ячеек коротким. Экранируйте черты обратной косой.

markdown
| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

Сложная таблица

Таблицы масштабируются по строкам и колонкам, но остаются простыми в ячейке. Для кода с запятыми оборачивайте в обратные кавычки. Экранируйте буквальную черту через \|. Сложные данные (многострочные ячейки, вложенные таблицы) требуют HTML <table>. Если таблица слишком широка, подумайте о списке.

markdown
| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

Советы и ограничения таблиц

Таблицы Markdown ограничены: нельзя объединять ячейки, делать многострочное содержимое, блочные элементы и вложенные таблицы. Для этого используйте чистый HTML. Держите таблицы небольшими и обозримыми. Если нужны сноски или длинный текст, разделите таблицу. Инструменты вроде TablesGenerator.com ускоряют сборку.

markdown
| A | B |
|---|---|
| 1 | 2 |

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>
10

Сноски

Базовые сноски

Сноски используют маркеры [^id] в тексте и определение [^id]: в другом месте. id может быть числом или словом. Рендереры создают кликабельные надстрочные номера и раздел сносок внизу. Поддерживается GFM, Pandoc и большинством современных парсеров.

markdown
Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

Несколько ссылок на сноску

На сноску можно ссылаться несколько раз: каждый [^id] ведёт к одному определению. Строки продолжения определения имеют отступ. Первая ссылка обычно получает надстрочный номер, последующие ведут к той же сноске.

markdown
Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

Встроенные сноски

Встроенные сноски (^[текст]) вставляют содержимое прямо в месте ссылки; поддерживаются Pandoc и некоторыми расширениями (не ядром GFM). Всё остаётся в одном месте, но может прерывать чтение. Используйте для коротких заметок; длинные лучше выносить в обычные сноски.

markdown
Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

Размещение сносок

Определения сносок можно размещать в любом месте документа: рендереры собирают их и показывают в конце. Строки продолжения с отступом 4 пробела. Сноски работают внутри блок-цитат и элементов списка. Позиция в исходнике не влияет на позицию в выводе.

markdown
Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

Сноски с кодом и форматированием

Определения сносок поддерживают встроенный Markdown (жирный, курсив, код) и несколько абзацев (продолжение с отступом 4 пробела). Блокам кода внутри сносок нужно 8 пробелов. Держите сноски краткими: длинный технический текст лучше в основном тексте или приложении.

markdown
See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote
11

Списки определений

Базовый список определений

Списки определений: термин на одной строке, затем двоеточие (:) и определение. Поддерживается PHP Markdown Extra, Pandoc и некоторыми расширениями (не ядром GFM). Выводится как <dl><dt><dd>. Полезно для глоссариев и пар термин-определение.

markdown
Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

Несколько терминов

Несколько подряд идущих терминов (без двоеточий) могут делить одно определение. Каждый термин становится <dt>, определение — <dd>. Полезно, когда у понятия несколько названий или синонимов. Держите термины на отдельных строках.

markdown
CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

Несколько определений

Несколько подряд идущих определений (каждое с двоеточия) для одного термина создают несколько <dd>. Полезно для перечисления разных значений или аспектов термина. Каждая строка с двоеточием — отдельная запись определения.

markdown
Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

Вложенные списки определений

Вложенные списки определений требуют отступа внутреннего списка (2-4 пробела) внутри внешнего определения. Поддержка парсеров различается: не все обрабатывают вложенность. Для сложных иерархий терминов надёжнее HTML <dl>. Тестируйте в целевом рендерере.

markdown
Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

Списки определений с блоками

Записи списка определений могут содержать несколько абзацев, блок-цитаты и блоки кода: отступите продолжение на 4 пробела (сверх двоеточия). Блокам кода внутри нужно всего 8 пробелов. Это мощно, но хрупко: сложное содержимое надёжнее в HTML <dl>.

markdown
Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)
12

Оглавление

Автоматическое оглавление

Большинство парсеров не генерируют оглавление по умолчанию. Некоторые (marked с плагином toc, MDX) поддерживают заглушки [TOC] или {:toc}. Инструменты вроде Doctoc и markdown-toc строят оглавление по заголовкам. В статических сайтах компоненты TOC читают якоря заголовков при сборке или на лету.

markdown
## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

Ручное оглавление

Ручное оглавление — вложенный список ссылок на якоря заголовков. Id якорей выводятся из текста заголовка (нижний регистр, дефисы вместо пробелов, пунктуация удалена). Отступы отражают иерархию заголовков. Обновляйте вручную при изменении заголовков или используйте генератор.

markdown
# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

Правила генерации якорей

Генерация якорей зависит от парсера. Частые правила: нижний регистр, пробелы в дефисы, удаление пунктуации, сохранение букв и цифр. GitHub сохраняет эмодзи и часть Unicode. Числа и точки часто удаляются. Если не уверены, посмотрите отрендеренный HTML, чтобы найти фактический id.

markdown
## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

Свои ID якорей

Для надёжных якорей добавляйте явные ID. Синтаксис атрибутов {#id} работает в Pandoc, marked и некоторых расширениях. Приём с HTML <a id="..."> работает везде: ставьте его до или внутри заголовка. Свои ID переживают изменение текста заголовка.

markdown
## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

Навигация по TOC и обратные ссылки

Ссылки «наверх» улучшают навигацию в длинных документах. HTML <details>/<summary> создаёт сворачиваемое оглавление — отлично для боковых панелей и длинных README. Сочетайте с якорными ссылками для плавной навигации. Добавьте scroll-margin-top в CSS для компенсации фиксированных шапок.

markdown
## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>
13

Эмодзи и спецсимволы

Шорткоды эмодзи

Шорткоды эмодзи (:name:) поддерживаются GitHub/GitLab (набор EmojiOne/Twemoji). Именованных эмодзи тысячи. Шорткоды удобны, но непереносимы: в парсерах без GFM они могут отобразиться буквально. Для максимальной совместимости используйте сырые Unicode-эмодзи.

markdown
:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

Частые эмодзи

Большинство современных редакторов и рендереров работают с сырыми Unicode-эмодзи напрямую: просто вставьте. Шорткоды специфичны для GitHub. Эмодзи передают тон и статус (галочка и крестик для результатов, баг для ошибок). В формальных документах используйте редко; в README и changelog они уместны.

markdown
:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

HTML-сущности

HTML-сущности работают в Markdown, так как он проходит в HTML. Используйте &amp; для буквального амперсанда (особенно в URL и атрибутах), &lt; &gt; для угловых скобок, &copy; &reg; &trade; для символов. Числовые (&#169;) и шестнадцатеричные (&#x00A9;) формы покрывают любой символ Unicode.

markdown
&amp;  &lt;  &gt;  &quot;  &apos;

&copy;  &reg;  &trade;

&mdash; &ndash; &hellip;

&#169;  &#x00A9;

Use &amp; to show a literal &.

Специальные символы

Markdown по умолчанию не превращает обычную пунктуацию в типографские символы (умные кавычки): используйте HTML-сущности или вставляйте Unicode. Длинные тире и фигурные кавычки улучшают типографику. Многие редакторы автозаменяют их. Для стрелок и символов сущности понятнее.

markdown
-- em dash (or &mdash;)
-- en dash (or &ndash;)
... ellipsis (or &hellip;)
' ' curly quotes (&lsquo; &rsquo;)
" " curly quotes (&ldquo; &rdquo;)
-> arrow (or &rarr;)
(tm) (r) (c)

Эмодзи и Markdown вместе

Эмодзи сочетаются со всеми элементами Markdown: заголовками, списками, жирным, ссылками, цитатами. Они добавляют визуальные подсказки в changelog, README и шаблонах задач. Держите использование эмодзи последовательным (например, единое соглашение для changelog). Избегайте эмодзи в формальном и академическом письме.

markdown
## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)
14

Диаграммы Mermaid

Блок-схема Mermaid

Mermaid — текстовый язык диаграмм, который рендерят GitHub, GitLab и многие генераторы статических сайтов. Оборачивайте код Mermaid в ограждённый блок mermaid. flowchart TD (сверху вниз) или LR (слева направо) задаёт направление. Узлы используют [], {}, () для разных форм.

markdown
```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Диаграмма последовательности Mermaid

Диаграммы последовательности показывают взаимодействия участников во времени. ->> — сплошная стрелка (запрос), -->> — пунктирная (ответ). participant объявляет участников. Полезно для документирования потоков API, протоколов и обмена сообщениями. Автоматически рендерится на GitHub.

markdown
```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Диаграмма классов Mermaid

Диаграммы классов моделируют объектно-ориентированные структуры. + означает public, - private, # protected. <|-- обозначает наследование. Mermaid поддерживает ассоциации, композиции и интерфейсы. Отлично для документирования архитектуры кода прямо в Markdown.

markdown
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

Диаграмма состояний Mermaid

Диаграммы состояний показывают переходы. [*] отмечает начальное и конечное состояния. Стрелки подписывают переходы событиями (state --> state: event). Полезно для документирования протоколов, состояний UI и жизненного цикла объектов. stateDiagram-v2 — современный синтаксис.

markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Диаграмма Ганта Mermaid

Диаграммы Ганта визуализируют график проекта. dateFormat задаёт разбор дат. Задачи используют id, start, duration (например, 7d). 'after a1' связывает задачи. Секции группируют связанные задачи. Полезно для README и планов проектов: рендерится на GitHub без внешних инструментов.

markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Круговая диаграмма Mermaid

Круговые диаграммы показывают доли в процентах (значения относительны). Заголовок необязателен. Подписи в кавычках, значения после двоеточия. Mermaid также поддерживает git-графы, ER-диаграммы, карты пути и ментальные карты — всё рендерится в Markdown на поддерживаемых платформах.

markdown
```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```
15

GitHub Flavored Markdown

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

Списки задач GitHub Flavored Markdown (GFM) рендерятся как интерактивные флажки на GitHub. [x] отмечено, [ ] нет. Работают в issues, PR, комментариях и README. В списках issues показываются индикаторы прогресса. Синтаксис теперь широко поддерживается и вне GitHub.

markdown
- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

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

GFM добавляет зачёркивание (~~текст~~) к стандартному Markdown. Работает через строки и сочетается с другим форматированием. Выводится как <del>. Изначально расширение GFM, теперь в дополнениях к CommonMark. Полезно для правок и пометок об устаревании.

markdown
~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

Таблицы (GFM)

Таблицы — возможность GFM (не исходного Markdown). Обязателен синтаксис с чертами, строкой заголовка и разделителем. Таблицы GFM поддерживают выравнивание, встроенное форматирование и экранированные черты. Для сложных таблиц (объединение, вложенность) используйте HTML.

markdown
| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

Оповещения GitHub

Оповещения GitHub (2023+) используют маркер [!TYPE] в первой строке блок-цитаты: NOTE, TIP, IMPORTANT, WARNING, CAUTION. На GitHub они рендерятся с разными цветами и иконками. Отлично для врезок в README и документации. Синтаксис специфичен для GitHub.

markdown
> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

Запрещённый сырой HTML

GFM фильтрует сырой HTML ради безопасности: <script>, <style>, <title>, иногда <iframe> и обработчики событий вырезаются. Это предотвращает XSS в пользовательском контенте. Безопасный HTML вроде <details>, <kbd>, <sup> проходит. Знайте белый список своего рендерера, смешивая HTML.

markdown
GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

Автоссылки (GFM)

GFM автоматически связывает голые URL (https://...) и домены www. без угловых скобок. Для переносимости угловые скобки (<url>) работают во всех вариантах. Автоссылки могут удивлять: берите угловые скобки, когда нужно показать URL буквально рядом с другим текстом.

markdown
Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.
16

Расширенный синтаксис

Выделение

Синтаксис выделения ==текст== — расширение (не в GFM и CommonMark), поддерживается некоторыми парсерами, например Markdown-it с плагином. HTML-тег <mark> поддерживается везде. Используйте выделение для акцента на ключевых терминах; злоупотребление снижает эффект.

markdown
==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

Нижний и верхний индекс

Нижний (~текст~) и верхний (^текст^) индексы — расширения Pandoc/markdown-it, не стандарт. Для универсального отображения используйте HTML <sub>/<sup> или Unicode. Полезно в научном и математическом контенте на Markdown.

markdown
H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

Синтаксис атрибутов

Синтаксис атрибутов {#id .class key=val} (Pandoc, некоторые плагины markdown-it) прикрепляет HTML-атрибуты к элементам. Полезно для хуков стилизации, своих якорей и целей ссылок. Непереносим: в неподдерживающих парсерах остаётся буквальным текстом. Используйте редко.

markdown
## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

Свои контейнеры

Свои контейнеры (:::type ... :::) поддерживаются VuePress, Docusaurus, VitePress и похожими инструментами документации. Они рендерятся как стилизованные блоки-врезки. type отображается в CSS-класс. Хорошо для тематической документации, но непереносимо в обычные рендереры Markdown.

markdown
:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

Математика и LaTeX (KaTeX)

Поддержка математики зависит от рендерера: GitHub поддерживает $...$ в строке и $$...$$ блоком (с MathJax/KaTeX). Не все парсеры Markdown поддерживают математику. Для максимальной совместимости рендерите математику в изображения или используйте MathJax напрямую. Полезно для научно-технической документации.

markdown
Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.
17

Инструменты и редакторы

VS Code

В VS Code встроен предпросмотр Markdown и богатая экосистема расширений. Markdown All in One добавляет сокращения (жирный, оглавление, предпросмотр). markdownlint следит за стилем. Preview Enhanced поддерживает диаграммы, математику и экспорт. Настройте перенос слов для удобного редактирования.

markdown
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora

Typora — популярный WYSIWYG-редактор Markdown: он рендерит на месте по мере ввода, избавляя от разделённых панелей. Поддерживает GFM, таблицы, блоки кода, математику и Mermaid. Экспортирует во многие форматы встроенными средствами. Платный, но отточенный; хорош для письма.

markdown
Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian

Obsidian хранит заметки как локальные файлы Markdown с мощными возможностями: wiki-ссылки, обратные ссылки, граф, теги. Он расширяет Markdown врезками, встраиванием и Dataview. Идеален для Zettelkasten и личной базы знаний. Бесплатен для личного использования.

markdown
Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

Markdown Lint

markdownlint следит за единым стилем файлов Markdown. Правила настраиваются в .markdownlint.json. Часто отключают: MD013 (длина строки) для прозы, MD033 (встроенный HTML), когда HTML нужен. MD040 напоминает помечать блоки кода языком. Интегрируется с CI и редакторами.

markdown
# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc

Pandoc — «швейцарский нож» конвертации документов: Markdown в HTML, PDF, Word, LaTeX, EPUB, слайды и обратно. Поддерживает расширения Markdown (цитаты, математику, списки определений, сырые атрибуты). Флаг -s создаёт автономные документы. Необходим в академических и издательских процессах.

markdown
# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

Онлайн-редакторы

Онлайн-редакторы хороши для быстрых правок и обмена. StackEdit и Dillinger — полнофункциональные одиночные редакторы. HackMD/HedgeDoc добавляют совместную работу в реальном времени. Веб-редактор GitHub имеет вкладку Preview. Все поддерживают стандартный Markdown; возможности GFM лучше всего работают в редакторе GitHub.

markdown
Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.
18

Лучшие практики

Читаемость прежде всего

Главный принцип Markdown — читаемость как обычного текста. Предпочитайте самый читаемый синтаксис: # для заголовков, - для списков, **жирный**. Избегайте чрезмерной вложенности и обильного форматирования. Если исходник приятно читать в текстовом редакторе, вы хорошо используете Markdown.

markdown
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

Длина строк и переносы

Два допустимых подхода: жёсткий перенос (одно предложение на строку) даёт чистые git-диффы и простое редактирование; мягкий (один абзац на строку) избавляет от переформатирования. Выберите один на проект и будьте последовательны. Настройте ширину переноса в редакторе (обычно 80-120 символов).

markdown
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

Последовательность

Markdown предлагает несколько синтаксисов для одного результата (жирный ** против __, списки - против * против +). Выберите одно соглашение на проект и следите за ним через markdownlint. Последовательность снижает нагрузку на читателей и контрибьюторов и упрощает автоматическую обработку.

markdown
# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

Лучшие практики ссылок

Для длинных URL используйте ссылки-справочники, чтобы проза оставалась читаемой. Для коротких локальных ссылок — встроенные. Описательный текст ссылки улучшает доступность и SEO: избегайте «нажмите здесь». Заголовки добавляют контекст через подсказки. Группируйте определения ссылок в конце раздела или документа.

markdown
# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

Доступность

Доступность важна и в Markdown: осмысленный alt-текст для изображений (пустой для декоративных), описательный текст ссылок (не «нажмите здесь»), правильная иерархия заголовков (не пропускайте уровни) и семантический HTML (kbd, abbr, cite) там, где Markdown не хватает. Скринридеры зависят от этого.

markdown
# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

Частые ошибки

Частые ловушки: отсутствие пустых строк вокруг блочных элементов (списки, цитаты, код), непоследовательные отступы в вложенных списках, незакрытые ограждения кода и смешение табов с пробелами. Всегда просматривайте предпросмотр перед публикацией. Запускайте markdownlint для автоматического поиска проблем. Тестируйте в целевом рендерере.

markdown
# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.