Как написать блок кода в Markdown:огородите его тремя обратными кавычками.

Блоки кода с ограждением

Ограждение — это строка минимум из трёх обратных кавычек, а блок заканчивается строкой не короче открывающей. Всё между ними показывается как набрано: без жирного, без ссылок, без склейки строк.

```
plain text, no colors
  indentation is kept
```

Вместо этого можно взять три тильды: ~~~ открывает, ~~~ закрывает. Эти два вида не смешиваются: блок, открытый тильдами, должен закрываться тильдами. Блок кода получится и при отступе каждой строки на четыре пробела — это старый стиль, но в нём нельзя указать язык, поэтому ограждения лучше.

Теги языка и подсветка синтаксиса

Слово после открывающего ограждения называется info string. Большинство приложений по нему выбирают подсветку:

```json
{ "name": "dotmd", "private": true }
```

Распространённые названия, которые работают на GitHub, в DotMD и в большинстве других приложений:

• js или javascript, ts или typescript, python, swift, go, rust
• bash, sh или zsh для команд оболочки
• json, yaml, html, css, sql
• markdown или md, чтобы показать сам Markdown, diff для изменений, text — без цветов

Точный список названий зависит от приложения и его подсветки. Название, которого приложение не знает, не ошибка: блок просто показывается без цветов. Блок без языка тоже показывается без подсветки.

Обратные кавычки внутри блока кода

Если в коде есть строка из трёх обратных кавычек, огородите блок более длинным ограждением. Закрывающее ограждение должно быть не короче открывающего, поэтому чтобы показать три, возьмите четыре:

````markdown
```swift
let x = 1
```
````

Именно так на этой странице показаны примеры Markdown с блоками кода. С ограждением из тильд то же самое: блок, открытый ~~~~, может содержать ~~~.

Строчный код

Для команды или имени внутри предложения оберните их в одиночные обратные кавычки: `npm install` даёт npm install. Чтобы показать обратную кавычку, заключите всё в двойные обратные кавычки и добавьте пробел внутри, если код начинается или заканчивается обратной кавычкой:

``a `tick` inside``

Строчный код ещё и не даёт символам вроде * и _ восприниматься как разметка, поэтому он подходит для имён файлов и переменных.

Код в списках и цитатах

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

1. Install the tool:

   ```bash
   brew install example
   ```

2. Run it.

Поставьте пустую строку перед ограждением и сдвигайте все строки кода на одинаковую величину. В цитате начинайте каждую строку ограждения с >.

Блоки diff

Пометьте блок как diff, и строки, начинающиеся с + или -, получат зелёный и красный цвета в приложениях, которые подсвечивают diff, включая GitHub:

```diff
- let timeout = 30
+ let timeout = 60
```

Это удобный способ показать изменение в документации, README или спецификации без скриншотов.

Частые ошибки

• Закрывающее ограждение короче открывающего, из-за чего блок не заканчивается и поглощает остаток страницы.
• Пробелы перед тегом языка в строгих приложениях. Если цвета не появились, пишите ```js, а не ``` js.
• Обратные кавычки и тильды в одном блоке.
• Нет пустой строки перед ограждением после пункта списка или абзаца в некоторых приложениях. Добавьте её.
• Фигурные кавычки. Текст, вставленный из текстового редактора, может превратить прямые кавычки в коде в фигурные. Вставляйте как простой текст.

Не все ограждения нужны для показа кода. Блок с пометкой mermaid GitHub и DotMD рисуют как диаграмму, если синтаксис верный.

Проверка цветов

Быстрее всего тег языка проверяется в программе для чтения. DotMD подсвечивает блоки с ограждением через highlight.js в светлой и тёмной темах и показывает кнопку Copy при наведении на блок. Чтение бесплатно, а остальной синтаксис собран на одной странице в шпаргалке по Markdown.

Вопросы о блоках кода в Markdown

Другие вопросы