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

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

В тексте

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

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

Результат:

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

Если текст содержит двойные фигурные скобки, но не предполагает подстановку переменной, добавьте перед конструкцией 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 %}

Параметр 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:.