You can include code in your documents using the standard markup syntax of ```language, where language is the programming language for highlighting.

Code blocks

The above code is not a directive, it is just standard markdown syntax, which cannot add a caption or label. To caption or label blocks of code use the code-block directive.

Numbering and Highlighting

To add numbers and emphasis to lines, we are following the sphinx code-block directive. You can use linenos which is a flag, with no value, and emphasize-lines with a comma-separated list of line numbers to emphasize.

1
2
3
4
```{code-block}
:linenos:
:emphasize-lines: 2,3
...

Emphasize lines inside of a code block.

You can also set the start number using the lineno-start directive, and all emphasized lines will be relative to that number.

code-block reference

linenos (no value)
Show line numbers for the code block
lineno-start (number)
Set the first line number of the code block. If present, linenos option is also automatically activated.
Default line numbering starts at 1.
emphasize-lines (string)
Emphasize lines of the code block, for example, 1, 2 highlights the first and second lines.
The line number counting starts at lineno-start, which is by default 1.
caption (string)
Add a caption to the code block.
name (string)
The target label for the code-block, can be used by ref and numref roles.
Alternative implementations

The parser also supports the docutils implementation (see docutils documentation) of a {code} directive, which only supports the number-lines option.

It is recommended to use the more fully featured code-block directive documented above, or a simple markdown code block.

All implementations are resolved to the same code type in the abstract syntax tree.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication