MarkdownCo
Назад в блог
Руководства

Расширенный синтаксис Markdown: полное руководство с примерами

Изучите все элементы расширенного синтаксиса Markdown: таблицы, блоки кода, сноски, списки задач, эмодзи и другое с наглядными примерами для практики.

Расширенный синтаксис Markdown: полное руководство с примерами

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

Не все процессоры Markdown поддерживают все элементы расширенного синтаксиса. Перед использованием проверьте, поддерживает ли ваш инструмент или платформа нужную вам функцию. Хорошая новость: большинство современных платформ — GitHub, GitLab, VS Code и популярные генераторы статических сайтов — поддерживают большинство этих расширений.

Если вы ещё не освоили основы, начните с нашего руководства по базовому синтаксису Markdown.

Таблицы

Markdown Tables

Таблицы позволяют организовать данные в строки и столбцы прямо в Markdown. Используйте вертикальные черты (|) для разделения столбцов и дефисы (-) для создания строки заголовка.

| Feature       | Basic Syntax | Extended Syntax |
| ------------- | ------------ | --------------- |
| Tables        | No           | Yes             |
| Footnotes     | No           | Yes             |
| Task Lists    | No           | Yes             |

Результат отображения:

FeatureBasic SyntaxExtended Syntax
TablesNoYes
FootnotesNoYes
Task ListsNoYes

Выравнивание столбцов

Управляйте выравниванием текста, добавляя двоеточия в строку-разделитель заголовка:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More         |     More       |          More |
  • :--- выравнивание по левому краю (по умолчанию)
  • :---: выравнивание по центру
  • ---: выравнивание по правому краю

Советы по таблицам

  • Вам не нужно идеально выравнивать вертикальные черты в исходном коде — это лишь для аккуратности
  • Таблицы поддерживают строчное форматирование: жирный, курсив, код и ссылки
  • Таблицы не поддерживают заголовки, цитаты, списки или изображения внутри ячеек
  • Для сложных данных рассмотрите использование HTML-таблиц

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

Markdown Fenced Code Blocks

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

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
```

Результат с полной подсветкой синтаксиса:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))

Поддерживаемые языки

Большинство рендереров поддерживают десятки идентификаторов языков. Вот наиболее распространённые:

Language        Identifier
--------------  ----------------
JavaScript      javascript / js
Python          python / py
TypeScript      typescript / ts
HTML            html
CSS             css
JSON            json
Bash            bash / sh
SQL             sql
Markdown        markdown / md

Лучшие практики для блоков кода

  • Всегда указывайте язык — это включает подсветку синтаксиса и улучшает читаемость
  • Используйте text или plaintext, когда язык не применим
  • Огороженные блоки предпочтительнее блоков с отступами, так как поддерживают подсветку и не требуют отступа каждой строки

Сноски

Markdown Footnotes

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

Markdown was created by John Gruber in 2004.[^1] It has since become
the standard for technical writing.[^2]

[^1]: John Gruber's original Markdown project is documented on
    [Daring Fireball](https://daringfireball.net/projects/markdown/).
[^2]: Markdown is used by GitHub, Stack Overflow, Reddit, and
    countless other platforms.

Номера ссылок отображаются как надстрочные ссылки в тексте, а полные примечания перечислены внизу документа.

Правила синтаксиса сносок

  • Ссылка на сноску использует [^identifier] — идентификатор может быть числом или словом (без пробелов)
  • Определение сноски начинается с [^identifier]:, за которым следует содержимое
  • Многоабзацные сноски требуют отступа (четыре пробела или один таб) для последующих абзацев
  • Определения сносок можно размещать в любом месте документа — они всегда отображаются внизу
Here's a footnote with multiple paragraphs.[^note]

[^note]: This is the first paragraph of the footnote.

    This is the second paragraph, indented with four spaces.

    You can even include code: `console.log("hello")`

Идентификаторы заголовков

Пользовательские идентификаторы заголовков позволяют создавать точные якорные ссылки на конкретные разделы документа. Добавьте ID в фигурных скобках после текста заголовка.

### My Custom Section {#custom-section}

Это генерирует:

<h3 id="custom-section">My Custom Section</h3>

Ссылки на идентификаторы заголовков

Когда заголовок имеет ID, можно ссылаться прямо на него:

Jump to [My Custom Section](#custom-section).

Это особенно полезно для создания ручного оглавления в начале длинных документов:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)
- [FAQ](#faq)

Примечание о совместимости

Многие процессоры (включая GitHub) автоматически генерируют ID заголовков из текста заголовка даже без синтаксиса {#id}. Однако явная установка ID даёт полный контроль и обеспечивает согласованное поведение на разных платформах.

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

Списки определений идеально подходят для глоссариев, FAQ и любого контента, где нужно сопоставить термины с их объяснениями.

Markdown
: A lightweight markup language for creating formatted text
  using a plain-text editor.

HTML
: The standard markup language for documents designed to be
  displayed in a web browser.

YAML
: A human-readable data serialization language commonly used
  for configuration files.

Это генерирует следующий HTML:

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for creating formatted text
      using a plain-text editor.</dd>
  <dt>HTML</dt>
  <dd>The standard markup language for documents designed to be
      displayed in a web browser.</dd>
</dl>

Множественные определения

Термин может иметь несколько определений:

Markdown
: A lightweight markup language.
: A tool used by developers and writers worldwide.

Примечание о совместимости

Списки определений поддерживаются не всеми процессорами. GitHub Flavored Markdown их не поддерживает, но многие генераторы статических сайтов и инструменты документации поддерживают.

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

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

The project deadline is ~~Friday~~ Monday.
~~Old information~~ has been replaced with updated content.

Результат отображения:

The project deadline is Friday Monday.

HTML-вывод:

<p>The project deadline is <del>Friday</del> Monday.</p>

Зачёркивание широко поддерживается — оно входит в GitHub Flavored Markdown (GFM) и работает на большинстве современных платформ.

Списки задач

Markdown Task Lists

Списки задач (также называемые чекбоксами или списками дел) создают интерактивные чеклисты. Используйте - [ ] для невыполненных пунктов и - [x] для выполненных.

- [x] Research extended syntax features
- [x] Write first draft
- [x] Add code examples for each section
- [ ] Create cover image
- [ ] Proofread and edit
- [ ] Publish the article

Результат отображения:

  • Research extended syntax features
  • Write first draft
  • Add code examples for each section
  • Create cover image
  • Proofread and edit
  • Publish the article

Сценарии использования списков задач

Списки задач особенно популярны в:

  • Issues и pull requests на GitHub — отслеживание прогресса рабочих задач
  • Документация проектов — описание шагов процесса
  • Заметки совещаний — фиксация задач и их статуса

На платформах вроде GitHub эти чекбоксы интерактивны — можно кликнуть для переключения прямо в отрендеренном виде.

Эмодзи

Есть два способа добавить эмодзи в документы Markdown.

Копирование и вставка

Самый простой подход — просто скопируйте эмодзи из любого источника и вставьте прямо в текст:

That's a great idea! 🎉 Let's ship it! 🚀

Это работает везде, потому что эмодзи — стандартные символы Unicode.

Короткие коды

Некоторые платформы поддерживают короткие коды эмодзи — ключевые слова в двоеточиях:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

Распространённые короткие коды:

Shortcode              Emoji
---------------------  -----
:smile:                😄
:rocket:               🚀
:thumbsup:             👍
:warning:              ⚠️
:heavy_check_mark:     ✔️
:x:                    ❌
:fire:                 🔥
:star:                 ⭐

Примечание о совместимости

Короткие коды эмодзи различаются между платформами. GitHub, Slack и Discord поддерживают разные наборы. Скопированные и вставленные эмодзи работают везде и являются более надёжным выбором для кроссплатформенных документов.

Выделение

Выделение привлекает внимание к ключевым словам или фразам, давая им цветной фон. Оберните текст двойными знаками равенства (==).

This is ==critically important== information.

Это генерирует:

<p>This is <mark>critically important</mark> information.</p>

HTML-альтернатива

Если ваш процессор Markdown не поддерживает синтаксис ==, используйте HTML-тег <mark> напрямую:

This is <mark>critically important</mark> information.

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

Примечание о совместимости

Синтаксис ==highlight== не поддерживается широко. Он работает в некоторых процессорах, но не в GitHub Flavored Markdown. Если совместимость важна, используйте HTML-тег <mark>.

Подстрочный и надстрочный текст

Эти элементы необходимы для научной нотации, математических выражений и химических формул.

Подстрочный текст

Используйте одинарные тильды (~) для обёртки подстрочного текста:

The chemical formula for water is H~2~O.
Carbon dioxide is CO~2~.

Результат: H2O и CO2.

HTML-эквивалент:

<p>The chemical formula for water is H<sub>2</sub>O.</p>

Надстрочный текст

Используйте каретки (^) для обёртки надстрочного текста:

The equation is E = mc^2^.
This is the 3^rd^ edition.

Результат: E = mc2 и 3-е издание.

HTML-эквивалент:

<p>The equation is E = mc<sup>2</sup>.</p>

HTML-альтернатива

Если ваш процессор не поддерживает синтаксис ~ и ^, используйте HTML-теги напрямую:

H<sub>2</sub>O is water.
E = mc<sup>2</sup> is Einstein's famous equation.

Этот HTML-подход работает практически в любом рендерере Markdown.

Автоматические URL-ссылки

Большинство процессоров Markdown автоматически преобразуют необработанные URL в кликабельные ссылки без специального синтаксиса:

Visit https://example.com for more information.

Это отображается как кликабельная ссылка даже без синтаксиса [text](url).

Отключение автоматических ссылок

Иногда вы хотите отобразить URL как обычный текст без возможности клика. Оберните его обратными кавычками для отображения как строчного кода:

`https://example.com`

Это отображает URL как код, а не как кликабельную ссылку — полезно для документации, где вы объясняете шаблоны URL, а не ссылаетесь на них.

Когда использовать явные ссылки

Хотя автоматические ссылки удобны, синтаксис явных ссылок даёт больше контроля:

<!-- Automatic: shows raw URL -->
https://example.com

<!-- Explicit: shows custom text -->
[Visit our website](https://example.com)

Используйте явные ссылки, когда хотите описательный текст якоря — это лучше для читаемости и SEO.

Краткий справочник

Markdown Extended Syntax Quick Reference

Все элементы расширенного синтаксиса одним взглядом:

Element              Syntax                     Support
-------------------  -------------------------  --------
Table                | Col | Col |              Wide
Fenced Code Block    ``` code ```               Wide
Footnote             [^1] / [^1]: text          Moderate
Heading ID           ### Heading {#id}          Moderate
Definition List      Term / : Definition        Limited
Strikethrough        ~~text~~                   Wide
Task List            - [x] / - [ ]             Wide
Emoji (shortcode)    :emoji_name:               Varies
Highlight            ==text==                   Limited
Subscript            H~2~O                      Limited
Superscript          X^2^                       Limited
Auto URL Link        https://...                Wide

Начните использовать расширенный синтаксис

Теперь вы знаете все основные элементы расширенного синтаксиса. Вот как применить их на практике:

  1. Проверьте вашу платформу: Убедитесь, какие функции поддерживает ваш процессор Markdown. GitHub, VS Code и большинство генераторов статических сайтов хорошо обрабатывают широко поддерживаемые элементы.

  2. Используйте HTML-альтернативы: Для функций с ограниченной поддержкой (выделение, подстрочный, надстрочный текст) HTML-теги работают практически везде.

  3. Практикуйтесь на реальном контенте: Попробуйте добавить таблицу в ваш следующий README, сноски в следующую статью блога или списки задач в следующий план проекта.

  4. Конвертируйте уверенно: Когда документ готов к публикации, конвертируйте Markdown в PDF для вывода, готового к печати, с поддержкой таблиц и формул LaTeX, экспортируйте в HTML для веб-публикации или создайте документ Word для рецензирования — все элементы расширенного синтаксиса включены.

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

MarkdownРасширенный синтаксисТекстыПродуктивность