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 для отображения изменений в коде, которые могут выделять добавленные или удаленные строки в обзорах кода.
• Чтобы отобразить обратные кавычки внутри блока кода, оберните блок в большее количество обратных кавычек (например, четыре обратные кавычки для отображения трех обратных кавычек).

Вывод

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

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

Чтобы эффективно использовать подсветку синтаксиса diff в блоках кода Markdown, следуйте следующим шагам:

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

Пример:

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

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

Рекомендации:

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

Совет:
Этот метод широко поддерживается на платформах вроде GitHub, GitLab и многих рендерерах Markdown, делая его надежным выбором для визуального обмена изменениями в коде.

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

Блоки кода Markdown поддерживают широкий спектр языков для подсветки синтаксиса, но конкретный набор поддерживаемых языков зависит от рендерера или платформы, которую вы используете. Сам Markdown не определяет, какие языки поддерживаются; он просто передает идентификатор языка рендеринговому движку, который затем применяет соответствующую подсветку синтаксиса. Заблокированные блоки кода Markdown сами по себе не определяют фиксированный набор официально поддерживаемых языков программирования. Вместо этого список поддерживаемых языков зависит от рендерера Markdown или платформы, которую вы используете (например, GitHub, GitLab, VS Code, Typora, Quarto и т.д.).

Часто поддерживаемые языки на основных платформах (например, 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, c++, 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!")
```

Следующие языки поддерживаются большинством рендереров Markdown:

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

Как найти полный список поддерживаемых языков:

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

Основные моменты:

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

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

Чтобы указать имя файла в блоке кода Markdown, у вас есть несколько вариантов, но метод зависит от платформы и рендерера:

1. Имя файла в мета-синтаксисе блока кода

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

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

Это отобразит имя файла (например, app.js) над или рядом с блоком кода, в зависимости от рендерера. А на этой веб-странице рендерер Hugo не делает это:

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

Примечание: Это не поддерживается всеми платформами (например, GitHub-флavored Markdown в настоящее время не поддерживает эту функцию).

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

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

**`app.js`**

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

Или:

#### `app.js`

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

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

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

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

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

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

Итог и рекомендации

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

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

• Инструменты документации в 2026 году: Markdown, LaTeX, PDF и рабочие процессы печати
• Справочник по Markdown — наиболее полезные структуры и команды
• Справочник по Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks