Code fragments
A code fragment can be added to the text or placed in a separate block.
In text
To add a code fragment to the text, use the ` character.
`Фрагмент кода` в тексте.
Result:
Code fragment in text.
If the text contains double curly braces but does not imply variable substitution, add not_var before the construct.
The prefix not_var works only for code fragments consisting of characters .-|(),_, a-z, A-Z, 0-9 and spaces.
Tip
It is recommended to use no more than 100 characters, as text in such a fragment is not wrapped. For a larger number of characters, format the code as a separate block.
As a separate block
To format a code fragment as a separate block, separate it from the rest of the text on both sides with ``` characters.
For syntax highlighting, specify the language in which the code is written in the opening line. For example:
```sql
price= '2000'
size= '24'
color= 'primary'
variant= 'detailed'
```
Examples of supported languages
- apache;
- bash;
- coffeescript;
- cpp;
- cs;
- css;
- diff;
- go;
- http;
- ini;
- java;
- javascript;
- json;
- kotlin;
- less;
- lua;
- makefile;
- xml;
- markdown;
- nginx;
- objectivec;
- perl;
- php;
- plaintext;
- properties;
- python;
- ruby;
- rust;
- scss;
- shell;
- sql;
- swift;
- typescript;
- yaml.
See the highlight.js documentation for the full list of languages and aliases. Available languages depend on the version and language set of the installed highlighting library; third-party languages must be loaded separately.
Displaying line numbers
If you need to enable line numbers in a code block, use the keyword showLineNumbers.
Usage example:
```sql showLineNumbers
price = '2000'
size = '24'
color = 'primary'
variant = 'detailed'
```
Result:
1 price = '2000'
2 size = '24'
3 color = 'primary'
4 variant = 'detailed'
Line wrapping by default
To enable soft wrap by default in a code block, use the keyword wrap.
Usage example:
``` wrap
Очень длинная строка в блоке кода, которая точно не поместится в длину, если её искусственно не свернуть
```
Result:
Очень длинная строка в блоке кода, которая точно не поместится в длину, если её искусственно не свернуть
Command line prefix
Use the parameter prompt="<value>" to exclude the command line prefix ($, #, >>>, mysql>, etc.) from selection and copying via the widget.
Usage example:
```bash prompt="$"
$ npm install
$ npm run build
```
Result:
npm install
npm run build
Tip
This feature is especially useful for snippets. If a code block contains only commands, without their output, the user can copy the entire content with one button and paste it into the terminal — without selecting lines individually.
Including code from a file
Use the {% code %} directive to include a local file as a code block:
{% code "./examples/main.ts" lang="typescript" %}
A path without a leading / is relative to the current Markdown file. A path with a leading / is relative to the documentation project root.
The lang parameter sets the code block language for syntax highlighting. It supports the same languages and aliases as regular code blocks: for example, typescript or ts, javascript or js, python or py, bash or sh, sql, json, yaml, xml or html. If the parameter is omitted or the highlighting library does not recognize the language, the code is displayed without highlighting. The language is not detected automatically from the file extension.
See the highlight.js documentation for the full list of lang values and aliases.
To enable line numbers, append showLineNumbers after the language inside the lang value:
{% code "./examples/main.ts" lang="typescript showLineNumbers" %}
Numbering starts at 1 for the displayed fragment, even when lines selects it from the middle of a file. The lines parameter selects a fragment and does not control the display of line numbers.
By default, the common indentation is removed from all non-empty lines. Add keep-indents to preserve the original indentation:
{% code "./examples/main.ts" keep-indents %}
Named regions
To include a named region from a local file, append #<region-name> to its path:
{% code "./examples/main.ts#auth" lang="typescript" %}
Mark the region boundaries in the source file using either convention:
// #region auth
connect();
// #endregion auth
// [START auth]
connect();
// [END auth]
Both conventions can be used in the same file. Names are case-sensitive, must be unique within the file, and may contain ASCII letters, digits, _, ., /, and -. A bare #endregion closes the innermost open region. As in the source conventions, markers are recognized anywhere on a line without parsing the programming language; put them on dedicated comment lines because the entire marker line is removed.
The keywords #region and #endregion must be followed by a space, tab, end of line or block-comment terminator (*/ or -->). Text such as #region-banner and #endregion-old is not a marker and remains part of the selected code. Opening markers still require a region name.
Nested regions are supported. Selecting an outer region includes the code of its inner regions, with all marker lines removed. Inner regions can also be selected independently. Surrounding blank lines are removed, while keep-indents controls the indentation of the selected code. Rendering options such as showLineNumbers and wrap remain available through lang.
The build fails if the requested region is missing or empty, a name is duplicated, a marker is unmatched, or the boundaries violate nesting. The entire region structure of each file referenced by #<region-name> is validated. Diagnostics identify the documentation page, source file, region, and reason. For example:
index.md: Code directive: region "auth" was not found while including "./examples/main.ts#auth".
Whole-file inclusion without a fragment and legacy lines inclusion do not perform these region checks. You cannot combine a named region and lines in one directive.
If the file path contains #
File and directory names may contain literal # characters, for example ./C#/Program.cs. By default, if the complete path names an existing file, that file is included. Only when the complete path does not name a file is the final # interpreted as the region separator: ./C#/Program#v2.cs#auth selects auth from ./C#/Program#v2.cs. If a file named example.ts#auth exists, it takes precedence over the auth region in example.ts. Legacy lines also works with literal # paths.
A suffix after the final # containing /./ or /../ segments, including a trailing /. or /.., is always treated as a region name without probing a literal file path. These segments remain part of the region name. For example, ./example.ts#section/../other.ts selects the region section/../other.ts from example.ts.
Legacy substring markers
The lines parameter is retained for compatibility and emits an informational INFO notice recommending path#region. This deprecation notice does not fail a --strict build and is hidden by --quiet. Other warnings, such as missing substring markers or ignored directive attributes, still fail strict builds. The parameter includes part of a file by providing two substring markers separated by -. The lines containing the markers are excluded.
To migrate, replace arbitrary markers such as [BEGIN auth] / [END auth] with one of the supported region conventions, then replace lines="..." with #auth in the path. For the bracket convention, use [START auth], not [BEGIN auth]. No removal date for lines has been set.
For example, examples/main.ts contains:
const before = 1;
// [A]
console.log('Hello');
// [B]
const after = 2;
To include the code between the [A] and [B] markers, specify them in the lines parameter:
{% code "./examples/main.ts" lang="typescript" lines="[A]-[B]" %}
Result:
console.log('Hello');
The lines values are substring markers. For example, lines="2-3" specifies the markers 2 and 3, rather than source file line numbers.
If the start or end marker is missing, the CLI emits a code directive warning and uses the beginning or end of the file, respectively. If the end marker occurs before the start marker, the builder emits a warning and creates an empty code block.
For a directive with lines="[A]-[B]" in index.md, the warnings look like this:
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".
The message identifies the Markdown file containing the directive, the reason for the warning, and the included file path. Each warning is emitted only when its corresponding condition occurs.
These warnings do not have a dedicated MD or YFM code: their messages use the Code directive: prefix.