Фрагменты кода

Фрагмент кода можно добавить в текст или вынести в отдельный блок.

В тексте

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

`Фрагмент кода` в тексте.

Результат:

Фрагмент кода в тексте.

Если текст содержит двойные фигурные скобки, но не предполагает подстановку переменной, добавьте перед конструкцией not_var.

Префикс not_var работает только для фрагментов кода, состоящих из символов .-|(),_, a-z, A-Z, 0-9 и пробелов.

Отдельным блоком

Чтобы оформить фрагмент кода как отдельный блок, отделите его от остального текста с двух сторон символами ```.

Для подсветки синтаксиса укажите в начальной строке язык, на котором написан код. Например:

```sql
  price= '2000'
  size= '24'  
  color= 'primary'
  variant= 'detailed' 
```

Полный перечень языков и их коротких имён приведён в документации highlight.js. Доступные языки зависят от версии и набора языков установленной библиотеки подсветки; сторонние языки требуют отдельного подключения.

Отображение номеров строк

Если необходимо включить отображение номеров строк в блоке кода, используйте ключевое слово showLineNumbers.

Пример использования:

```sql showLineNumbers
  price = '2000'
  size = '24'  
  color = 'primary'
  variant = 'detailed' 
```

Результат:

1  price = '2000'
2  size = '24'
3  color = 'primary'
4  variant = 'detailed'

Перенос строк по умолчанию

Чтобы включить перенос строк (soft wrap) по умолчанию в блоке кода, используйте ключевое слово wrap.

Пример использования:

``` wrap
Очень длинная строка в блоке кода, которая точно не поместится в длину, если её искусственно не свернуть
```

Результат:

Очень длинная строка в блоке кода, которая точно не поместится в длину, если её искусственно не свернуть

Префикс командной строки

Используйте параметр prompt="<значение>", чтобы исключить префикс командной строки ($, #, >>>, mysql> и др.) из выделения и копирования через виджет.

Пример использования:

```bash prompt="$"
$ npm install
$ npm run build
```

Результат:

$ npm install
$ npm run build

Включение кода из файла

Чтобы включить содержимое локального файла как блок кода, используйте директиву {% code %}:

{% code "./examples/main.ts" lang="typescript" %}

Путь без начального / задаётся относительно текущего Markdown-файла. Путь с начальным / — относительно корня проекта документации.

Параметр lang задаёт язык блока для подсветки синтаксиса. Поддерживаются те же языки и короткие имена, что и в обычных блоках кода: например, typescript или ts, javascript или js, python или py, bash или sh, sql, json, yaml, xml или html. Если параметр не указан или язык неизвестен библиотеке подсветки, код отображается без подсветки. Язык не определяется автоматически по расширению файла.

Полный список значений lang и коротких имён приведён в документации highlight.js.

Чтобы включить отображение номеров строк, добавьте showLineNumbers после языка внутри значения lang:

{% code "./examples/main.ts" lang="typescript showLineNumbers" %}

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

По умолчанию из всех непустых строк удаляется общий отступ. Чтобы сохранить исходные отступы, добавьте параметр keep-indents:

{% code "./examples/main.ts" keep-indents %}

Именованные регионы

Чтобы включить именованный регион из локального файла, добавьте #<имя-региона> к его пути:

{% code "./examples/main.ts#auth" lang="typescript" %}

Отметьте границы региона в исходном файле одним из двух способов:

// #region auth
connect();
// #endregion auth

// [START auth]
connect();
// [END auth]

Оба формата можно использовать в одном файле. Имена чувствительны к регистру и должны быть уникальными в пределах файла. Разрешены латинские буквы, цифры, _, ., / и -. Метка #endregion без имени закрывает ближайший открытый регион. Метки распознаются в любом месте строки без разбора языка программирования. Размещайте их в отдельных строках-комментариях: строка с меткой целиком удаляется из результата.

После ключевых слов #region и #endregion должны стоять пробел, табуляция, конец строки или завершающий символ блочного комментария (*/ либо -->). Текст вида #region-banner и #endregion-old не считается меткой и остаётся в выбранном коде. Открывающая метка по-прежнему должна содержать имя региона.

Регионы могут быть вложенными. При выборе внешнего региона включается и код внутренних регионов, а все строки-маркеры удаляются. Внутренний регион можно выбрать отдельно. Пустые строки по краям фрагмента удаляются. Параметр keep-indents управляет отступами выбранного кода. Параметры оформления showLineNumbers и wrap по-прежнему доступны через lang.

Сборка завершается ошибкой, если выбранный регион отсутствует или пуст, имя повторяется, метка осталась без пары или границы нарушают вложенность. Для каждого файла, подключённого через #<имя-региона>, проверяется вся структура регионов. Сообщение указывает страницу документации, исходный файл, регион и причину. Например:

index.md: Code directive: region "auth" was not found while including "./examples/main.ts#auth".

При включении файла целиком без фрагмента и при использовании старого lines эти проверки регионов не выполняются. Совмещать именованный регион и lines в одной директиве нельзя.

Если в пути к файлу есть символ #

Имена файлов и каталогов могут содержать буквальный символ #, например ./C#/Program.cs. По умолчанию, если полный путь указывает на существующий файл, включается этот файл. Только если такого файла нет, последняя решётка считается разделителем региона: ./C#/Program#v2.cs#auth выбирает auth из ./C#/Program#v2.cs. Если существует файл example.ts#auth, он имеет приоритет перед регионом auth в example.ts. Старый параметр lines также работает с буквальным # в пути.

Суффикс после последней решётки с сегментами /./ или /../, в том числе с завершающими /. или /.., всегда считается именем региона без проверки буквального пути к файлу. Эти сегменты остаются частью имени региона. Например, ./example.ts#section/../other.ts выбирает регион section/../other.ts из example.ts.

Старый способ: подстроки-маркеры

Параметр lines сохранён для совместимости. При его использовании сборщик выводит информационное уведомление уровня INFO и рекомендует path#region. Это уведомление об устаревшем способе не останавливает сборку с --strict и скрывается при --quiet. Другие предупреждения, например об отсутствующих подстроках-маркерах или проигнорированных атрибутах директивы, по-прежнему останавливают строгую сборку. Параметр позволяет включить часть файла по двум подстрокам-маркерам, разделённым -. Строки с маркерами в результат не включаются.

Для перехода замените произвольные метки, например [BEGIN auth] / [END auth], одним из поддерживаемых форматов регионов, а lines="..." — на #auth в пути. Для формата со скобками используется [START auth], а не [BEGIN auth]. Дата удаления lines не назначена.

Например, файл examples/main.ts содержит:

const before = 1;
// [A]
console.log('Hello');
// [B]
const after = 2;

Чтобы включить код между маркерами [A] и [B], укажите их в параметре lines:

{% code "./examples/main.ts" lang="typescript" lines="[A]-[B]" %}

Результат:

console.log('Hello');

Значения lines задают подстроки-маркеры. Например, lines="2-3" означает маркеры 2 и 3, а не номера строк исходного файла.

Если начальный или конечный маркер не найден, CLI выводит предупреждение директивы code и использует соответственно начало или конец файла. Если конечный маркер расположен раньше начального, сборщик выводит предупреждение и создаёт пустой блок кода.

Для директивы с lines="[A]-[B]" в файле index.md предупреждения выглядят так:

index.md: Code directive: start marker "[A]" was not found; using the beginning of the file while including "./examples/main.ts".
index.md: Code directive: end marker "[B]" was not found; using the end of the file while including "./examples/main.ts".
index.md: Code directive: end marker "[B]" occurs before start marker "[A]"; the fragment is empty while including "./examples/main.ts".

В сообщении указаны Markdown-файл с директивой, причина предупреждения и путь к включаемому файлу. Каждое предупреждение выводится только при соответствующей ситуации.

У этих предупреждений нет отдельного кода MD или YFM: в сообщении используется префикс Code directive:.