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

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

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

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

Блоки кода в Markdown отображают код или предварительно отформатированный текст в документах Markdown, сохраняя форматирование и, при необходимости, обеспечивая подсветку синтаксиса. Существует два основных типа форматирования кода в Markdown: встроенный код и блоки кода.

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

Основные различия

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

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

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

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

Отображаемый результат выглядит так:

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

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

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

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

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

Краткое справочное руководство

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

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

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

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

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

Пример:

- старая строка, которая будет удалена
+ новая строка, которая будет добавлена
  неизмененная строка

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

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

• Размещайте пустую строку перед и после блока кода для лучшей читаемости в исходном 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)
• Другие: 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!");

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

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