Блоки кода в Markdown: полное руководство по синтаксису, языкам и примерам

Здесь я рассматриваю Варианты блоков кода в Markdown — как указать язык программирования, форматирование diff и имя файла в блоке кода.

Это руководство является частью нашего центра Инструменты для документации в 2026 году: Markdown, LaTeX, PDF и рабочие процессы печати.

Обзор блоков кода в Markdown

Блоки кода в Markdown отображают код или предварительно отформатированный текст внутри документов Markdown, сохраняя форматирование и опционально включая подсветку синтаксиса. В Markdown существует два основных типа форматирования кода: встроенный код (inline code) и блоки кода (code blocks).

Типы блоков кода в Markdown

Ключевые различия

• Встроенный код использует одиночные обратные апострофы (`) и применяется для коротких фрагментов кода внутри предложения.
• Отступные блоки кода используют четыре пробела или табуляцию в начале каждой строки. Они не поддерживают подсветку синтаксиса и редко используются в современном Markdown.
• Закрытые блоки кода (Fenced code blocks) используют тройные обратные апострофы (```) или тильды (~~~) перед и после кода. Это предпочтительный метод, особенно на платформах вроде GitHub, потому что:
  • Они легче читаются и пишутся.
  • Вы можете указать язык программирования сразу после открывающих апострофов для подсветки синтаксиса.
  • Они сохраняют форматирование и поддерживают многострочный код.

Пример закрытого блока кода с подсветкой синтаксиса:

Когда у нас есть следующий текст, отформатированный в Markdown:

```python
def hello():
    print("Hello, world!")
```

Результат рендеринга выглядит так:

def hello():
    print("Hello, world!")

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

• Используйте закрытые блоки кода (тройные обратные апострофы) для многострочного кода, чтобы обеспечить ясность и совместимость между платформами.
• Указывайте язык после открывающих апострофов для подсветки синтаксиса (например, ```python).
• Используйте встроенный код для коротких фрагментов или команд внутри текста.
• Избегайте отступных блоков кода, если это не требуется для обратной совместимости, так как они не поддерживают подсветку синтаксиса и могут быть менее читаемыми.
• Оставляйте пустую строку перед и после закрытых блоков кода для улучшения читаемости в исходном Markdown.

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

• Некоторые платформы поддерживают дополнительные идентификаторы языков, такие как diff для отображения изменений кода, который выделяет добавленные или удаленные строки при рецензировании кода.
• Чтобы отобразить обратные апострофы внутри блока кода, оберните блок в большее количество апострофов (например, четыре апострофа для отображения трех апострофов внутри).

Краткое резюме

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

Блоки кода естественно сочетаются с таблицами в Markdown для создания хорошо структурированной технической документации.

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

Подсветка синтаксиса Diff позволяет четко показывать изменения в коде — это полезно в документации, рецензировании кода и технических блогах.

• Используйте закрытые блоки кода с тройными обратными апострофами (```) для начала и завершения вашего блока.
• Укажите diff как идентификатор языка сразу после открывающих апострофов.

Пример:

- old line that will be removed
+ new line that will be added
  unchanged line

• Строки, начинающиеся с -, подсвечиваются как удаления (обычно красным).
• Строки, начинающиеся с +, подсвечиваются как добавления (обычно зеленым).
• Строки без префикса не выделяются специальным образом.

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

• Оставляйте пустую строку перед и после вашего блока кода для лучшей читаемости в исходном Markdown.
• Обратите внимание, что подсветка diff окрашивает только целые строки в зависимости от ведущего символа; она не выделяет изменения внутри строки.

Совет: Подсветка Diff широко поддерживается на GitHub, GitLab и большинстве рендереров Markdown, что делает ее надежным выбором для демонстрации изменений в коде.

Поддерживаемые языки для подсветки синтаксиса

Точный набор поддерживаемых языков зависит от рендерера или платформы, которую вы используете. Markdown передает идентификатор языка движку рендеринга, который применяет соответствующую подсветку синтаксиса. Это важно при конвертации HTML в Markdown с помощью Python, поскольку теги <code> с атрибутами классов языка (например, class="language-python") напрямую сопоставляются с этими идентификаторами в закрытом блоке.

Общеупотребительные поддерживаемые языки на крупных платформах (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Веб и скрипты: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Программирование: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Данные и запросы: sql, r, matlab
• Разметка и конфигурация: markdown, ini, toml, dockerfile, makefile
• Специальные: diff, mermaid, geojson, topojson, stl (для диаграмм и визуализации данных на GitHub) — идентификатор mermaid в частности позволяет полноценный рендеринг диаграмм на поддерживаемых платформах; см. Быстрый старт и шпаргалку по диаграммам Mermaid для полного справочника по синтаксису и руководства по настройке Hugo
• Другие: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme и многие другие

Как указать язык:

```python
def hello():
    print("Hello, world!")
```

Идентификаторы языков, поддерживаемые большинством рендереров:

Примечание: Большинство рендереров не чувствительны к регистру названий языков. Если вы используете неподдерживаемый идентификатор, блок кода отобразится как обычный текст.

Поиск полного списка поддерживаемых языков:

• GitHub: Использует Linguist, поддерживая сотни языков.
• VS Code и многие веб-рендереры: Используют highlight.js или Pygments — см. их документацию для исчерпывающих списков.
• Bitbucket: Ссылается на режимы CodeMirror и лексеры Pygments.

Указание имени файла в блоке кода Markdown

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

1. Имя файла в метке блока кода (Синтаксис метаданных)

Некоторые движки Markdown (некоторые генераторы статических сайтов и платформы документации) поддерживают синтаксис метаданных, где вы добавляете имя файла после языка, разделяя их двоеточием:

```js:app.js
console.log("Hello, world!");
```

Это отображает имя файла над или рядом с блоком кода. Рендерер Hugo этого сайта не поддерживает это:

console.log("Hello, world!");

Примечание: Это не поддерживается в Markdown в стиле GitHub.

2. Ручное указание имени файла заголовком или встроенным кодом

Для универсальной совместимости (включая GitHub, Stack Overflow и большинство рендереров Markdown) разместите имя файла над блоком кода, используя жирный встроенный код:

**`app.js`**

```js
console.log("Hello, world!");
```

Или с заголовком:

#### `app.js`

```js
console.log("Hello, world!");
```

Это работает везде и визуально связывает имя файла с блоком кода.

3. Имя файла как комментарий внутри кода

Включите имя файла как комментарий внутри самого блока кода:

```js
// app.js
console.log("Hello, world!");
```

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

Резюме совместимости

Используйте жирный встроенный код над блоком кода для максимальной совместимости, и рассмотрите возможность добавления комментария внутри кода для ясности при обмене между платформами.

Экранирование обратных апострофов внутри блоков кода

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

````markdown
```python
# Это ограждение из трех апострофов находится внутри ограждения из четырех апострофов
print("hello")
```
````

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

Специфика Hugo: Шорткод Highlight

Если вы используете Hugo, встроенный шорткод highlight предлагает больше контроля, чем простые закрытые блоки, включая номера строк и выделение строк:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Опции:

• linenos=true — показать номера строк
• hl_lines=2 4 — выделить строки 2 и 4
• linenostart=10 — начать нумерацию строк с 10

Это особенно полезно в учебных пособиях или документации, где вы хотите привлечь внимание к конкретным строкам. См. Шпаргалку по Markdown для большего количества возможностей форматирования, и Шпаргалку по Hugo для более широкого справочника по командам и шаблонам Hugo.

Полезные ссылки

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks