Markdown Extensions¶

All of the following are available in any .md page on this site. Extensions are grouped by what they do.

Callouts & admonitions¶

Admonitions¶

Block-level callout boxes. The keyword after !!! sets the type and colour.

!!! note "Optional custom title"
    Body text goes here, indented by four spaces.

!!! warning
    Title defaults to the type name if omitted.

Available types: note info tip success question warning danger bug example quote

Collapsible details¶

Swap !!! for ??? to make a callout collapsible. Add + to start it open:

??? tip "Click to expand"
    This content is hidden until the user opens it.

???+ warning "Open by default"
    Starts expanded.

Code¶

Fenced code blocks¶

Use triple backticks with an optional language identifier for syntax highlighting:

```powershell
Get-ChildItem -Path C:\Users -Recurse
```

Line numbers:

```python linenums="1"
def hello():
    print("hello world")
```

Highlight specific lines:

```yaml hl_lines="2 3"
plugins:
  - search
  - awesome-pages
```

Add a title:

```bash title="Install dependencies"
pip install mkdocs-material
```

Code annotations¶

Add numbered annotations to code blocks using # (1) markers. The content.code.annotate theme feature must be on (it is):

```yaml
site_name: TheHive # (1)!
```

1. This is the title shown in the browser tab and the social card.

Inline code highlighting¶

Use #! followed by the language inside backticks for inline syntax:

Run `#!python print("hello")` in the console.

Mermaid diagrams¶

Fenced blocks with the mermaid language identifier render as diagrams:

```mermaid
graph LR
    A[Write docs] --> B[Build site] --> C[Ship it]
```

Supported diagram types: graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, pie, and more — see Mermaid docs.

Content layout¶

Tabbed content¶

Group content under switchable tabs. All tab sets with the same labels stay in sync across the page (content.tabs.link is on):

=== "Windows"
    ```powershell
    winget install git
    ```

=== "Linux"
    ```bash
    sudo apt install git
    ```

=== "macOS"
    ```bash
    brew install git
    ```

Grid cards¶

A responsive card grid. Requires attr_list and md_in_html (both enabled):

<div class="grid cards" markdown>

-   :material-file-document:{ .lg .middle } **Card Title**

    ---

    Description text goes here.

    [:octicons-arrow-right-24: Link text](target.md)

</div>

Icons use the :material-icon-name: or :octicons-icon-name: syntax — see the emoji section below.

Attribute lists¶

Add HTML classes, IDs, or attributes to any element. Used for buttons, image sizing, and custom styling:

[Primary button](url){ .md-button .md-button--primary }
[Secondary button](url){ .md-button }

![Image](img.png){ width="400" }

Lists¶

Task lists¶

- [x] Completed item
- [ ] Incomplete item
- [x] Another done item

Definition lists¶

Term
:   The definition of the term goes here.

Another term
:   Its definition.

Text formatting¶

Highlighting, underline, strikethrough, superscript, subscript¶

Keyboard keys¶

Renders key combinations as styled key caps:

Press ++ctrl+alt+del++ to open Task Manager.
Press ++enter++ to confirm.

Available key names: Ctrl, Alt, Shift, Win, Tab, Enter, Esc, F1 through F12, letter/number keys, and more — see the Keys docs.

Smart symbols¶

Automatic typographic replacements:

Tables¶

Standard GitHub-Flavoured Markdown tables. Alignment is set with colons in the separator row:

| Left | Centre | Right |
|:-----|:------:|------:|
| A    |   B    |     C |

Links & references¶

MagicLink¶

URLs written as plain text are automatically made into clickable links — no brackets needed:

See https://example.com for details.

GitHub references are also auto-linked when the repo is configured: user/repo#123 becomes a link to that issue.

Abbreviations¶

Define abbreviations once in a page (or a shared snippets file) and every occurrence is automatically given a tooltip:

The HTML spec defines how CSS is rendered.

*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets

Footnotes¶

This is a claim that needs a source.[^1]

[^1]: Source text goes here — rendered at the bottom of the page.

Table of contents¶

The toc extension with permalink: true adds a # anchor link to every heading, making sections directly linkable. The sidebar ToC is provided by the theme and follows your scroll (toc.follow is on).

Emoji & icons¶

Use Material, Octicons, or FontAwesome icon shortcodes anywhere in content:

:material-check-circle:  done
:octicons-alert-16:  warning
:fontawesome-brands-github:  GitHub

Browse available icons at squidfunk.github.io/mkdocs-material/reference/icons-emojis.

Math¶

Inline math uses \( … \), display (block) math uses \[ … \]:

Inline: The formula is \(E = mc^2\).

Block:
\[
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
\]

Rendered by MathJax, loaded from CDN. Standard LaTeX notation applies.