Markdown extensions

Netdocs renders Markdown with Markdig, configured to closely match the Material for MkDocs / Python-Markdown feature set. Many extensions are always on; others are enabled via markdownExtensions in appsettings.json.

Always-on extras

The shared pipeline enables these by default:

Built-in block extensions

Admonitions

!!! note "Heads up"
    Body text here.

???+ tip "Open by default"
    Collapsible content.

Content tabs

=== "Python"
    ```python
    print("hi")
    ```

=== "C#"
    ```csharp
    Console.WriteLine("hi");
    ```

Enable content.tabs.link in theme features to link tabs with the same label across the page.

Keyboard keys

Wrap a key combination in ++…++ to render Material keyboard keys:

Save with ++ctrl+s++ · quit with ++ctrl+alt+del++

Renders as:

Save with Ctrl+S · quit with Ctrl+Alt+Del

Common key names (ctrl, alt, shift, cmd, tab, esc, enter, arrows, f1–f24, …) get their Material glyph and label; anything else renders as a key-<name> <kbd>.

CriticMarkup

CriticMarkup annotations render inline. The Renders column below is live output:

Footnotes

Footnotes are always on. Reference a note inline with [^id] and define it anywhere in the document:

Here is a statement that needs a citation.[^src]

[^src]: The supporting detail, rendered at the foot of the page with a back-link.

Renders as:

Here is a statement that needs a citation.¹

The reference renders as a superscript link to the definition, and the definition gets a return arrow back to the reference. Hovering the reference shows the footnote content in a tooltip — this is enabled by the content.footnote.tooltips theme feature (add it to theme.features in appsettings.json), which mirrors Material's footnote-preview behaviour.

Emoji

Emoji shortcodes render as Twemoji SVG images (matching Material's pymdownx.emoji + twemoji generator):

Ship it :rocket:

Renders as:

Ship it — with love and a thumbs up

Emoji produce <img class="twemoji" …> elements served from a pinned jsDelivr CDN. To self-host the assets (or pin a different set), override the base URL:

"markdownExtensions": [
  { "name": "pymdownx.emoji", "options": { "base": "/assets/twemoji/" } }
]

Code blocks

Fenced code blocks are highlighted client-side (highlight.js) with line numbers. Use ```mermaid fences for Mermaid diagrams.

The pymdownx.highlight fence options are supported, in both the bare and the attr-list brace form:

```python linenums="5" hl_lines="2 4-5" title="example.py"
print("first")
print("highlighted")
```

```{ .yaml .no-copy title="config.yml" }
key: value
```

• linenums="N" — start the line-number gutter at N.
• hl_lines="2 4-5" — highlight the listed lines (ranges allowed).
• title="…" — render a file-name caption above the block.
• Line numbers are anchor-linkable (each line gets an id).

Inline code highlighting (pymdownx.inlinehilite) uses a shebang: `#!python range(10)` renders the span as highlighted python.

To include a maintained, tested region of a source file in a code block instead of copy-pasting, use snippet named sections.

Configurable extensions

Declared under markdownExtensions:

"markdownExtensions": [
  { "name": "admonition" },
  { "name": "attr_list" },
  { "name": "toc", "options": { "permalink": true } },
  { "name": "pymdownx.tabbed", "options": { "alternate_style": true } },
  { "name": "pymdownx.superfences" },
  { "name": "pymdownx.snippets", "options": { "base_path": [ "docs/_include" ] } }
]

• toc — permalink: true adds anchor links to headings.
• pymdownx.tabbed — content tabs (alternate style).
• pymdownx.superfences — nested fenced code / custom fences (e.g. Mermaid).
• pymdownx.snippets — file includes via --8<--.