Code blocks

Fenced code blocks are always available — no plugin or configuration is required. This page shows every supported feature rendered live next to the Markdown that produces it, so you can copy the exact syntax you need. Netdocs parses the same pymdownx.highlight fence options the MkDocs Material sites rely on, so most existing Markdown works unchanged.

Syntax highlighting is applied in the browser, and it is scheme-aware: token colors are mapped onto the theme's palette so code stays legible in both light and dark mode. The highlighter is swappable — see Code highlighting to switch it off or bring your own (Prism, Shiki, …).

Basic block

Wrap code in a triple-backtick fence and name the language after the opening fence. The language sets the syntax highlighting and is echoed onto the <code> element as language-<name>.

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

def greet(name: str) -> str:
    return f"Hello, {name}!"

A fence with no language is rendered as a plain, un-highlighted block:

```
$ netdocs build
```

Supported languages

Highlighting is powered by highlight.js and covers all of its "common" languages (Python, JavaScript/TypeScript, C#, Go, Rust, Java, Ruby, PHP, C/C++, JSON, YAML, XML/HTML, CSS, SQL, Bash/shell, Markdown, and more). Netdocs additionally registers several infrastructure languages that are not in that common set:

powershell, dockerfile, nginx, apache, http, dns (zone files), properties (.env / .properties), dart, scala, and x86asm.

Any language highlight.js does not recognise falls back to a plain block rather than erroring.

$ netdocs build

Copy button

Every code block gets a copy-to-clipboard button in its top-right corner (the content.code.copy theme feature, enabled by default). Hover a block to reveal it. Nothing extra is required in your Markdown.

Adding a title

Add title="…" to the fence to render a filename/label bar above the block. This is ideal for showing which file a snippet belongs to.

```json title="appsettings.json"
{
  "Netdocs": {
    "siteName": "My Site",
    "theme": { "name": "material" }
  }
}
```

{
  "Netdocs": {
    "siteName": "My Site",
    "theme": { "name": "material" }
  }
}

Line numbers

Add linenums="1" to number the lines, starting from the value you provide (so you can match an excerpt to its position in a larger file).

```python linenums="1"
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

Start numbering from an arbitrary line with linenums="42":

```python linenums="42"
    return n * factorial(n - 1)
```

    return n * factorial(n - 1)

Highlighting lines

Use hl_lines="…" to draw attention to specific lines. Line numbers here are relative to the block (line 1 is the first line of the fence, regardless of linenums). Accepts individual lines and ranges.

```python hl_lines="2 3"
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

Ranges use a hyphen, and you can mix ranges with single lines — hl_lines="1 3-4":

```python linenums="1" hl_lines="1 3-4"
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

Combining options

Options can be combined in any order on the same fence:

```python title="factorial.py" linenums="1" hl_lines="2 3"
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

Brace (attr-list) form

The pymdownx.highlight brace form is also accepted, so Markdown authored for MkDocs Material keeps working. The language is written as a leading .class:

```{.python title="factorial.py" hl_lines="2 3"}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

Inline code highlighting

Highlight a short inline snippet by starting an inline code span with a #! shebang followed by the language (the pymdownx.inlinehilite shebang syntax). For example, `#!python range(10)` renders as #!python range(10), while a plain `range(10)` stays un-highlighted.

Collapsing long blocks

Very long listings can dominate a page. Add the collapse flag to clip a block to the first 10 lines with a Show more / Show less toggle, or max-lines="N" to choose the height. The block only collapses when it is actually taller than the cap, so short snippets are unaffected.

```python collapse
# ... a long script ...
```

```python max-lines="6"
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

print(factorial(5))
print(factorial(6))
print(factorial(7))
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

print(factorial(5))
print(factorial(6))
print(factorial(7))

Both forms also work in the brace syntax — { .python max-lines="6" } or { .python collapse }.

Mermaid diagrams

A fence tagged mermaid is emitted as a diagram container and rendered in the browser by Mermaid — see the dedicated Mermaid diagrams page for all supported chart types and tips.

```mermaid
graph LR
  A[Markdown] --> B[Netdocs] --> C[HTML]
```

graph LR
  A[Markdown] --> B[Netdocs] --> C[HTML]

Supported fence options