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 default1
. - caption (string)
- Add a caption to the code block.
- name (string)
- The target label for the code-block, can be used by
ref
andnumref
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.