Skip to content

Code blocks

Usage

Adding a title

In order to provide additional context, a custom title can be added to a code block by using the title="<custom title>" option directly after the shortcode, e.g. to display the name of a file:

Code block with title
``` py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```
bubble_sort.py
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Adding annotations

Code annotations can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in // ... and /* ... */, for YAML in # ..., etc.1:

Code block with annotation
``` yaml
theme:
  features:
    - content.code.annotate # (1)
```

1.  :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted
    text**, images, ... basically anything that can be written in Markdown.

theme:
  features:
    - content.code.annotate # (1)
  1. 🙋‍♂️ I'm a code annotation! I can contain code, formatted text, images, … basically anything that can be written in Markdown.

Adding line numbers

Line numbers can be added to a code block by using the linenums="<start>" option directly after the shortcode, whereas <start> represents the starting line number. A code block can start from a line number other than 1, which allows to split large code blocks for readability:

Code block with line numbers
``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Highlighting specific lines

Specific lines can be highlighted by passing the line numbers to the hl_lines argument placed right after the language shortcode. Note that line counts start at 1, regardless of the starting line number specified as part of linenums:

Code block with highlighted lines
``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Highlighting inline code blocks

When [InlineHilite] is enabled, syntax highlighting can be applied to inline code blocks by prefixing them with a shebang, i.e. #!, directly followed by the corresponding [language shortcode][list of available lexers].

Inline code block
The `#!python range()` function is used to generate a sequence of numbers.

The range() function is used to generate a sequence of numbers.

Embedding external files

When Snippets is enabled, content from other files (including source files) can be embedded by using the --8<-- notation directly from within a code block:

Code block with external content
``` title=".browserslistrc"
--8<--​ ".browserslistrc"
```
.browserslistrc
last 4 years

  1. Code annotations require syntax highlighting with [Pygments] – they're currently not compatible with JavaScript syntax highlighters, or languages that do not have comments in their grammar. However, we're actively working on supporting alternate ways of defining code annotations, allowing to always place code annotations at the end of lines. ↩

Last update: March 22, 2022
Created: January 29, 2022
Back to top