Начало работы
Заголовки и абзацы
Используйте # для заголовков (1-6 уровней). Альтернативный синтаксис: === для H1 и --- для H2. Абзацы разделяются пустой строкой. 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>). Без них одиночный перевод строки — мягкий перенос, строки склеиваются в один абзац. Всегда оставляйте пустую строку между абзацами.
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-комментарии (<!-- -->) работают в большинстве рендереров и скрыты в выводе. Приём [//]: # использует пустую ссылку для заметок. Комментарии всё равно видны в исходнике.
<!-- HTML comments work in most Markdown -->
[//]: # (This is a comment)
[//]: # "Another comment style"
<!--
Multi-line comment
not rendered in output
-->Пробелы и отступы
Четыре ведущих пробела превращают текст в блок кода: остерегайтесь случайных отступов. Отступы важны для вложенных списков (2-4 пробела на уровень). Табуляция обычно считается 4 пробелами. Используйте пробелы последовательно, чтобы избежать проблем отображения в разных парсерах.
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>). Дефисы распространены чаще всего. Пробелы между символами допустимы. Для ясности ставьте пустые строки вокруг линии. Не путайте --- (линию) с # (заголовком).
---
***
___
* * *
Text above
---
Text belowФорматирование текста
Жирный (strong)
Двойные звёздочки или подчёркивания дают жирный текст (<strong>). Звёздочки предпочтительнее: подчёркивания не работают внутри слова (snake_case). Внутрь жирного можно вкладывать другие выделения. HTML-тег <strong> работает как запасной вариант.
**bold text**
__also bold__
**bold with *italic* inside**
<strong>HTML bold also works</strong>
**bold**Курсив (em)
Одинарные звёздочки или подчёркивания дают курсив (<em>). Звёздочки работают внутри слова; подчёркивания внутри слова считаются буквальными (поэтому no_italic_here). Запасной вариант — <em>. Курсив нужен для смыслового выделения, а не просто оформления.
*italic text*
_also italic_
*italic*
<em>HTML italic</em>
normal *italic* normalЖирный + курсив
Тройные звёздочки или подчёркивания дают и жирный, и курсив. Можно и вкладывать: жирный с курсивом или наоборот. Для отображен ия порядок не важен, но для читаемости его стоит выдерживать.
***bold and italic***
___also both___
**_bold and italic_**
*__bold and italic__*
combine **bold** and *italic*Зачёркивание
Двойные тильды (~~) создают зачёркивание — часть GitHub Flavored Markdown, теперь широко поддерживается. HTML-теги <del> и <s> — эквивалентные запасные варианты. В стандартном (исходном) Markdown зачёркивания нет.
~~strikethrough~~
~~crossed out text~~
<del>HTML delete</del>
<s>HTML strikethrough</s>
~~done~~ and ~~pending~~Mark / выделение
Двойное равно (==) для выделения — расширение, поддерживаемое некоторыми парсерами (не в ядре GFM). HTML-тег <mark> работает везде. Используйте выделение редко, чтобы акцентировать ключевые термины: злоупотребление снижает эффект.
==highlighted text==
<mark>HTML mark</mark>
This is ==important== text.
Compare **bold**, *italic*, ==mark==.Нижний и верхний индекс
Синтаксис тильды (нижний индекс) и каретки (верхний) (~ ~ и ^ ^) — расширения, которых нет в стандартном Markdown и GFM; поддерживаются Pandoc, R Markdown и немногими другими. Для универсальности используйте HTML <sub> и <sup> или символы Unicode.
H~2~O is water
E = mc^2^
x^2^ + y^2^ = r^2^
1st^st^ January
CO~2~ emissionsСписки
Маркированные списки
Используйте -, * или + для элементов маркированного списка: выберите один и будьте последовательны (- чаще всего). Вложенные элементы с отступом 2-4 пробела. Смешение маркеров в одном списке может вызывать проблемы в некоторых парсерах. Один элемент на строку.
- 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. для всех элементов, чтобы нумерация была автоматической.
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+ уровня) вредит читаемости — подумайте о переструктурировании. Держите отступы последовательными.
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, трекеров задач и отслеживания прогресса.
- [x] completed task
- [ ] incomplete task
- [ ] another todo
1. [x] done
2. [ ] not done
- [x] Write the docs
- [ ] Review PR
- [ ] DeployПлотные и разреженные списки
Если элементы разделены пустыми строками, список «разреженный» (каждый элемент обёрнут в <p>). Без пустых строк он «плотный» (без обёрток <p>). Это влияет на отступы в HTML. Добавляйте пустые строки осознанно, чтобы управлять обёрткой абзацев.
- tight item
- tight item
- tight item
- loose item
- loose item
- loose itemСписок с несколькими абзацами
Чтобы включить в элемент списка несколько абзацев или блочных элементов, отступите продолжение на 4 пробела (или выровняйте по содержимому маркера). Подблоки разделяются пустыми строками. Это необходимо для сложных списков, но легко ошибиться.
- First item
Second paragraph of first item.
- Second item
> A blockquote inside a list item.
>
> Must be indented to align.
- Third itemСсылки
Встроенные ссылки
Встроенные ссылки: [text](url). Необязательный заголовок в кавычках показывается как подсказка при наведении. Относительные ссылки работают для внутренней навигации. Якорные ссылки (#id) ведут к элементам с совпадающим id. В URL не должно быть пробелов: используйте %20.
[link text](https://example.com)
[link with title](https://example.com "Title here")
[relative link](/about)
[anchor](#section-id)Ссылки по ссылкам
Ссылки-справочники сохраняют читаемость текста, вынося URL. Определяйте ссылки в любом месте документа ([ref]: url). Определения не отображаются. Неявная форма [text][] использует сам текст как id ссылки. Ссылки можно переиспользовать.
[link text][ref]
[ref]: https://example.com "Optional title"
[link text][1]
[1]: https://example.com
[link text]
[link text]: https://example.comАвтоссылки и URL
Голые URL автоматически становятся ссылками в GitHub Flavored Markdown. Для соответствия стандарту заключайте URL в угловые скобки (<url>). Форма с угловыми скобками работает во всех вариантах Markdown. В некоторых парсерах автоссылки можно отключить.
https://example.com
<https://example.com>
<http://www.google.com>
Auto-linking bare URLs is supported
in GFM: visit https://example.com now.Автоссылки email
Адреса email в угловых скобках становятся кликабельными ссылками mailto:. Исходная спецификация Markdown поддерживала форму <text@domain>. Некоторые рендереры обфусцируют адреса, чтобы снизить сбор спама. Для публичных сайтов лучше форма обратной связи.
<[email protected]>
Contact: <[email protected]>
<John Doe <[email protected]>>
Mailto links work in most renderers.Заголовки ссылок
Заголовки ссылок показываются как подсказки при наведении. Заключайте заголовок в двойные или одинарные кавычки. Заголовки необязательны и служат подсказками для UX/SEO. Они не заменяют текст ссылки: скринридеры могут их игнорировать. Держите их краткими.
[hover for title](https://example.com "Example Site")
[reference with title][a]
[a]: https://example.com "Example Site"
[title with single quotes](https://example.com 'Single')Внутренние и якорные ссылки
Якоря заголовков в большинстве парсеров генерируются из текста заголовка (нижний регистр, пробелы в дефисы, пунктуация удаляется). Для своих ID используйте HTML <a id="..."> или расширение {#id} (Pandoc/marked). Якорные ссылки необходимы для оглавлений.
## Section Heading
[jump to Section](#section-heading)
[back to top](#top)
<a id="custom-id"></a>
[custom anchor](#custom-id)
## Heading {#explicit-id}Изображения
Базовое изображение
Синтаксис изображения как у ссылки, но с префиксом !. Alt-текст обязателен для доступности: он описывает изображение для скринридеров и показывается при ошибке загрузки. Путь может быть относительным, абсолютным или URL. Заголовок необязателен.


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


Изображение-ссылка
Оберните изображение в ссылку, вложив синтаксис изображения в синтаксис ссылки: [](url). Часто для миниатюр, ведущих на полный размер, бейджей со статусом CI и логотипов со ссылкой на главную. Alt-текст описывайте по назначению ссылки, а не только изображения.
[](https://example.com/full)
[](/)
[](https://ci.example.com)Изображения по ссылкам
Изображения-справочники используют тот же стиль, что и ссылки, с префиксом !. Определите ссылку на изображение один раз и переиспользуйте. Полезно, когда одно изображение встречается несколько раз, и для читаемости насыщенных изображениями абзацев.
![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) поддерживают {width=300}.
<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>Встроенный код и экранирование
Встроенный код
Заключайте встроенный код в одинарные обратные кавычки. Чтобы показать кавычки внутри кода, используйте двойные как разделитель (или больше). Встроенный код выводится моноширинным и не разбирается как Markdown. Отлично для имён файлов, команд и идентификаторов.
Use the `printf()` function.
Inline code: `const x = 42;`
Code with backticks: ``use `code` here``
A `<div>` element.Экранирование обратных кавычек
Чтобы включить обратную кавычку в код, используйте разделитель из большего числа кавычек, чем внутри: двойные вокруг одинарной. Вне кода обратную кавычку экранируют обратной косой. Закрывающий разделитель должен совпадать по длине с открывающим.
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: \`Код и пробелы
Встроенный код сохраняет внутренние пробелы точно. Частый приём: обернуть содержимое одним пробелом с каждой стороны, чтобы показать ведущие и замыкающие пробелы, которые иначе обрезались бы. По одному пробелу с каждой стороны удаляется автоматически.
` spaced ` (spaces preserved)
` code ` with one space pad
`function f() { return; }`
` multi word code `Экранирование обратной косой
Обратная косая экранирует специальные символы Markdown: обратную кавычку, звёздочку, подчёркивание, фигурные скобки, квадратные скобки, круглые скобки, решётку, плюс, минус, точку, восклицательный знак и саму обратную косую. Экранирование выводит символ буквально. Экранируйте только то, что иначе было бы воспринято как разметка.
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an imageКакие символы экранировать
Это экранируемые символы Markdown. Не все нужно экраниро вать везде: # важен только в начале строки, - в контексте списка и т. д. Сомневаетесь — экранируйте. Фигурные и круглые скобки обычно требуют экранирования только в особых контекстах (ссылки, строки шаблонов).
\\ backslash
\` backtick
\* asterisk
\_ underscore
\{ \} curly braces
\[ \] square brackets
\( \) parentheses
\# hash
\+ plus
\- minus
\. dot
\! exclamationБлоки кода
Блоки кода с отступом
Отступ в 4 пробела (или табуляция) создаёт блок кода. У таких блоков нет подсветки синтаксиса и языковой метки. Их нельзя использовать внутри элементов списка (считается продолжением). Для нового контента предпочитайте ограждённые блоки: отступные устарели.
Normal paragraph.
// indented code (4 spaces)
function hello() {
console.log("hi");
}
Back to normal text.Ограждённые блоки кода
Тройные обратные кавычки или тройные тильды создают ограждённый блок кода. Ограждения предпочтительнее отступов: они однозначны и поддерживают языковые подсказки. Тильды (~~~) удобны, когда в коде есть тройные обратные кавычки. Всегда закрывайте тем же числом символов.
```
plain code block
multiple lines
```
~~~
also a fenced block
using tildes
~~~Подсветка синтаксиса
Добавьте идентификатор языка сразу после открывающего ограждения для подсветки (например, js, python). Большинство рендереров используют highlight.js или Prism. Частые псевдонимы: js, ts, py, rb, sh, json, html, css. Если язык неизвестен, опустите его для простог о моноширинного текста.
```javascript
const greet = (name) => {
console.log(`Hello, ${name}!`);
};
```
```python
def greet(name):
print(f"Hello, {name}!")
```
```bash
echo "Hello, $USER"
```Вложенн ые ограждения
Чтобы показать обратные кавычки внутри блока кода, используйте другое ограждение (тильды для содержимого с кавычками или больше кавычек, чем внутри). Четыре обратные кавычки ограждают содержимое с тройными. Закрывающее ограждение должно совпадать по длине с открывающим.
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.
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).Блок-цитаты
Базовая блок-цитата
Символ > начинает блок-цитату. Можно ставить его в каждой строке или только в первой: большинство парсеров склеивают соседние строки. Блок-цитаты выводятся как сдвинутые стилизованные цитаты (<blockquote>). Используйте их для цитат, врезок и выделения фрагментов.
> 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.Многострочная блок-цитата
Используйте пустые строки с > для разделения абзацев внутри цитаты (иначе они сольются). > на пустой строке держит цитату открытой. Без пустых строк между абзацами текст идёт одним абзацем. Всегда закрывайте обычной строкой.
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.
End of quote.Вложенные блок-цитаты
Несколько символов > создают вложенные цитаты (>> для двух уровней, >>> для трёх). Добавляйте пробелы для читаемости. Глубокая вложенность (3+ уровня) плохо читается и стилизуется — лучше упростить. Каждый уровень добавляет отступ в HTML.
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer
> Outer
>> Deeper
>>> Deepest levelБлок-цитаты с другими элементами
Блок-цитаты могут содержать большинство элементов Markdown: заголовки, списки, код, выделения и даже таблицы. Префикс > (и пробел) в каждой строке удерживает их внутри цитаты. Это делает цитаты мощными для врезок, но сложное содержимое требует аккуратного выравнивания >.
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```Блок-цитата с источником
В Markdown нет формального синтаксиса цитирования. Частые соглашения: автор с длинным тире на новой строке или HTML <blockquote> с <footer> и <cite> для семантических ссылок. Для академических цитат рассмотрите сноску с источником.
> 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>Таблицы
Базовая таблица
В таблицах вертикальные черты (|) разделяют колонки, дефисы отделяют заголовок. Строка заголовка обязательна. Черты по краям строк необязательны, но улучшают читаемость. Ширина колонок не важна: ячейки подстраиваются. Таблицы — расширение GitHub Flavored Markdown.
| Name | Age | City |
|-------|-----|----------|
| Alice | 30 | NYC |
| Bob | 25 | London |
| Carol | 35 | Paris |Выравнивание ячеек
Двоеточия в строке-разделителе задают выравнивание: :--- влево, :---: по центру, ---: вправо. Без двоеточий по умолчанию влево. Выравнивание применяется ко всей колонке и задаёт text-align в HTML. Полезно для числовых колонок (вправо) и заголовков (по центру).
| Left | Center | Right |
|:-------|:------:|-------:|
| left | center | right |
| L | C | R |
| Default | alignment |
|---------|-----------|
| no mark | left |Таблица с форматированием
Ячейки могут содержать встроенный Markdown: жирный, курсив, код, ссылки, зачёркивание, эмодзи. Блочные элементы (заголовки, списки, блоки кода) внутри ячеек не работают: при необходимости используйте HTML. Держите содержимое ячеек коротким. Экранируйте черты обратной косой.
| Feature | Status | Notes |
|------------|:------:|--------------------|
| **Bold** | done | *finished* |
| `code` | wip | [docs](docs.md) |
| ~~old~~ | removed| gone in v2 |
| [link][1] | done | see [ref][1] |Сложная таблица
Таблицы масштабируются по строкам и колонкам, но остаются простыми в ячейке. Для кода с запятыми оборачивайте в обратные кавычки. Экранируйте буквальную черту через \|. Сложные данные (многострочные ячейки, вложенные таблицы) требуют HTML <table>. Если таб лица слишком широка, подумайте о списке.
| 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 ускоряют сборку.
| 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>Сноски
Базовые сноски
Сноски используют маркеры [^id] в тексте и определение [^id]: в другом месте. id может быть числом или словом. Рендереры создают кликабельные надстрочные номера и раздел сносок внизу. Поддерживается GFM, Pandoc и большинством современных парсеров.
Here is a sentence with a footnote.[^1]
[^1]: This is the footnote text.
Another sentence.[^note]
[^note]: Footnotes can use named labels.Несколько ссылок на сноску
На сноску можно ссылаться несколько раз: каждый [^id] ведёт к одному определению. Строки продолжения определения имеют отступ. Первая ссылка обычно получает надстрочный номер, последующие ведут к той же сноске.
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). Всё остаётся в одном месте, но может прерывать чтение. Используйте для коротких заметок; длинные лучше выносить в обычные сноски.
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 пробела. Сноски работают внутри блок-цитат и элементов списка. Позиция в исходнике не влияет на позицию в выводе.
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 пробелов. Держите сноски краткими: длинный технический текст лучше в основном тексте или приложении.
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Списки определений
Базовый список определений
Списки определений: термин на одной строке, затем двоеточие (:) и определение. По ддерживается PHP Markdown Extra, Pandoc и некоторыми расширениями (не ядром GFM). Выводится как <dl><dt><dd>. Полезно для глоссариев и пар термин-определение.
Term
: Definition of the term.
Markdown
: A lightweight markup language.
HTML
: HyperText Markup Language.Несколько терминов
Несколько подряд идущих терминов (без двоеточий) могут делить одно определение. Каждый термин становится <dt>, определение — <dd>. Полезно, когда у понятия несколько названий или синонимов. Держите термины на отдельных строках.
CSS
Cascading Style Sheets
: A style sheet language.
JS
JavaScript
: A programming language.
Both terms
: Share one definition.Несколько определений
Несколько подряд идущих определений (каждое с двоеточия) для одного термина создают несколько <dd>. Полезно для перечисления разных значений или аспектов термина. Каждая строка с двоеточием — отдельная запись определения.
Markdown
: A markup language.
: A tool for writing for the web.
Apple
: A fruit.
: A technology company.Вложенные списки определений
Вложенные списки определений требуют отступа внутреннего списка (2-4 пробела) внутри внешнего определения. Поддержка парсеров различается: не все обрабатывают вложенность. Для сложных иерархий терминов надёжнее HTML <dl>. Тестируйте в целевом рендерере.
Term
: Definition one.
Nested term
: Nested definition.
: Definition two for top term.Списки определений с блоками
Записи списка определений могут содержать несколько абзацев, блок-цитаты и блоки кода: отступите продолжение на 4 пробела (сверх двоеточия). Блокам кода внутри нужно всего 8 пробелов. Это мощно, но хрупко: сложное содержимое надёжнее в HTML <dl>.
Markdown
: A markup language.
With multiple paragraphs in the
definition (indent 4 spaces).
> Blockquote inside definition.
: Second definition with code:
indented code (8 spaces)Оглавление
Автоматическое оглавление
Большинство парсеров не генерируют оглавление по умолчанию. Некоторые (marked с плагином toc, MDX) поддерживают заглушки [TOC] или {:toc}. Инструменты вроде Doctoc и markdown-toc строят оглавление по заголовкам. В статических сайтах компоненты TOC читают якоря заголовков при сборке или на лету.
## 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 якорей выводятся из текста заголовка (нижний регистр, дефисы вместо пробелов, пунктуация удалена). Отступы отражают иерархию заголовков. Обновляйте вручную при изменении заголовков или используйте генератор.
# My Document
## Contents
- [Intro](#intro)
- [Setup](#setup)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Usage](#usage)
## Intro
...Правила генерации якорей
Генерация якорей зависит от парсера. Частые правила: нижний регистр, пробелы в дефисы, удаление пунктуации, сохранение букв и цифр. GitHub сохраняет эмодзи и часть Unicode. Числа и точки часто удаляются. Если не уверены, посмотрите отрендеренный HTML, чтобы найти фактический id.
## 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 переживают изменение текста заголовка.
## 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 для компенсации фиксированных шапок.
## Section
Content here.
[Back to top](#table-of-contents)
---
<details>
<summary>Table of Contents</summary>
- [Section 1](#section-1)
- [Section 2](#section-2)
</details>Эмодзи и спецсимволы
Шорткоды эмодзи
Шорткоды эмодзи (:name:) поддерживаются GitHub/GitLab (набор EmojiOne/Twemoji). Именованных эмодзи тысячи. Шорткоды удобны, но непереносимы: в парсерах без GFM они могут отобразиться буквально. Для максимальной совместимости используйте сырые Unicode-эмодзи.
:smile: :heart: :thumbsup: :rocket:
GFM supports shortcodes:
:sparkles: new feature :tada:
:checkered_flag: launch!
:bug: fixed issue #42Частые эмодзи
Большинство современных редакторов и рендереров работают с сырыми Unicode-эмодзи напрямую: просто вставьте. Шорткоды специфичны для GitHub. Эмодзи передают тон и статус (галочка и крестик для результатов, баг для ошибок). В формальных документах используйте редко; в README и changelog они уместны.
: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: zapHTML-сущности
HTML-сущности работают в Markdown, так как он проходит в HTML. Используйте & для буквального амперсанда (особенно в URL и атрибутах), < > для угловых скобок, © ® ™ для символов. Числовые (©) и шестнадцатеричные (©) формы покрывают любой символ Unicode.
& < > " '
© ® ™
— – …
© ©
Use & to show a literal &.Специальные символы
Markdown по умолчанию не превращает обычную пунктуацию в типографские символы (умные кавычки): используйте HTML-сущности или вставляйте Unicode. Длинные тире и фигурные кавычки улучшают типографику. Многие редакторы автозаменяют их. Для стрелок и символов сущности понятнее.