Skip to content

Mkdocs Reference

Below are quick copy and pastes I use often to quickly document:

Headers & File Info#

Metadata: Documentation Title#

---
title: Page name and top of tab
description: Google Search / SEO
date:
  created: 2025-11-16
  updated: 2024-11-17
---

## Section
### Sub Section

Metadata: Blog Title#

---
title: Page name and top of tab
description: Google Search / SEO
author: ComfyTechTips
date:
  created: 2025-11-16
  updated: 2025-11-17
slug: change-url-path
---

<Top of document and hook>

<!-- more -->

<Hidden>

## Section
### Sub Section

title: Lorem Ipsum # Custom title for .nav.yml root directory
hide: false # Hides .nav.yml root directory
ignore: "*.hidden.md" # Hides pattern for files matching
append_unmatched: true # Anything that isn't explicitly caught will go to end

sort:
  direction: asc
  type: natural
  by: title # some gotchas, read documentation
  sections: last
  ignore_case: true

nav:
  - one-i-want-first.md
  - "*" # the remaining files before directories and sections
  - Custom Title: Directory
  - Custom Title: File.md
  - i_want_to_flatten/a_sub/directory
  - Directory:
    - "*"
    - Some Website: https://lukasgeiter.github.io/mkdocs-awesome-nav

In-file Tools#

Admonition: Warning#

Warning

This will appear as a warning.

Warning Code 
!!! warning
    This will appear as a warning.

Admonition: Note (Collapsed and Inline End w/ Custom Name)#

My Warning

Careful, this code can be very dangerous if ran without prior caution.

Note Box Code 
??? note inline end "My Warning"
    Careful, this code can be very dangerous if ran without prior caution.

Admonition: Success (No title Box)#

RESULT

Success Box Code 
!!! success ""
    RESULT

Text: Emojis#

Official List

Emoji Code 
:fontawesome-brands-windows:

Text: Table#

Product What Link
GET Fetch resource <>
PUT Update resource <>
DELETE Delete resource <>
Table Code 
| Product      | What                                 | Link |
| :----------- | :----------------------------------- | :--- |
| `GET`        | :material-check:     Fetch resource  | <>   |
| `PUT`        | :material-check-all: Update resource | <>   |
| `DELETE`     | :material-close:     Delete resource | <>   |

Code Block: Line Numbering + Highlight#

1
2
3
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
Highlight Lines Code 
```python linenums="1" hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
```

Code Block: Title / Filename#

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]
Code with Title 
```python 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]
```

Selectable Tab: Multi-OS#

Windows way:

Write-Host "Hello"

Another way to say hello world:

echo -e "Hello"
Multi-OS Code 
=== "Windows"

    Windows way:

    ```powershell
    Write-Host "Hello"
    ```

=== "Ubuntu Linux"

    Another way to say hello world:

    ```bash
    echo -e "Hello"
    ```

Selectable Tab: Multi-Language#

To say hello:

print("Hello")

Another way to say hello world:

using System;

namespace HelloWorld
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello, World!");
        }
    }
}

Another way to say hello world:

(println "Hello, World!")
Multi-Language Code 
=== "Python"

    To say hello:

    ```python
    print("Hello")
    ```

=== "C#"

    Another way to say hello world:

    ```csharp
    using System;

    namespace HelloWorld
    {
        class Program
        {
            static void Main(string[] args)
            {
                Console.WriteLine("Hello, World!");
            }
        }
    }
    ```

=== "Clojure"

    Another way to say hello world:

    ```clojure
    (println "Hello, World!")
    ```

Images: Centered + Caption#

Image caption
Image with Caption Code 
<figure>
  <img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
  <figcaption>Image caption</figcaption>
</figure>

VSCode Snippet File#

Here's a VSCode snippets file to quickly paste the above:

Example:

VSCode Snippet File
.vscode/mkdocs-snippets.code-snippets
{
    "Title (Doc)": {
        "scope": "markdown",
        "prefix": "Title (Doc)",
        "body": [
            "---",
            "title: ${1:$TM_FILENAME_BASE}",
            "description: ${2:Google Search / SEO}",
            "date:",
            "    created: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
            "    updated: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
            "---",
            "$0"
        ],
        "description": "mkdocs title"
    },
    "Title (Blog)": {
        "scope": "markdown",
        "prefix": "Title (Blog)",
        "body": [
            "---",
            "title: ${1:$TM_FILENAME_BASE}",
            "description: ${2:Google Search / SEO}",
            "author: ComfyTechTips",
            "date:",
            "    created: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
            "    updated: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
            "slug: $TM_FILENAME_BASE",
            "---",
            "",
            "${3:Top of document and hook}",
            "",
            "<!-- more -->",
            "",
            "${4:Hidden content}",
            "$0"
        ],
        "description": "mkdocs blog post with author and slug"
    },
    "Warning Box": {
        "scope": "markdown",
        "prefix": "Warning Box",
        "body": [
            "!!! warning",
            "    ${1:This will appear as a warning.}",
            "$0"
        ],
        "description": "mkdocs warning admonition"
    },
    "Note Box (Collapsed, Inline End, Custom)": {
        "scope": "markdown",
        "prefix": "Note Box (Collapsed)",
        "body": [
            "??? note inline end \"${1:My Warning}\"",
            "    ${2:Careful, this code can be very dangerous if ran without prior caution.}",
            "$0"
        ],
        "description": "mkdocs collapsible note inline end with custom title"
    },
    "Success Box (No Title)": {
        "scope": "markdown",
        "prefix": "Success Box (No Title)",
        "body": [
            "!!! success \"\"",
            "    ${1:RESULT}",
            "$0"
        ],
        "description": "mkdocs success box without title"
    },
    "Code Block (Highlight Lines)": {
        "scope": "markdown",
        "prefix": "Code Block (Highlight Lines)",
        "body": [
            "```${1:python} linenums=\"1\" hl_lines=\"${2:2 3}\"",
            "${3:def bubble_sort(items):",
            "    for i in range(len(items)):",
            "        for j in range(len(items) - 1 - i):}",
            "```",
            "$0"
        ],
        "description": "code block with line numbers and highlighted lines"
    },
    "Code Block (With Title)": {
        "scope": "markdown",
        "prefix": "Code Block (With Title)",
        "body": [
            "```${1:python} title=\"${2:bubble_sort.py}\"",
            "${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]}",
            "```",
            "$0"
        ],
        "description": "code block with title"
    },
    "Multi-OS Tabs": {
        "scope": "markdown",
        "prefix": "Code Block Multi-OS",
        "body": [
            "=== \"${1:Windows}\"",
            "",
            "    ${2:Windows way:}",
            "",
            "    ```${3:powershell}",
            "    ${4:Write-Host \"Hello\"}",
            "    ```",
            "",
            "=== \"${5:Ubuntu Linux}\"",
            "",
            "    ${6:Another way to say hello world:}",
            "",
            "    ```${7:bash}",
            "    ${8:echo -e \"Hello\"}",
            "    ```",
            "$0"
        ],
        "description": "multi-OS tabbed content blocks"
    },
    "Multi-Language Tabs": {
        "scope": "markdown",
        "prefix": "Code Block Multi-Language",
        "body": [
            "=== \"${1:Python}\"",
            "",
            "    ${2:To say hello:}",
            "",
            "    ```${3:python}",
            "    ${4:print(\"Hello\")}",
            "    ```",
            "",
            "=== \"${5:C#}\"",
            "",
            "    ${6:Another way to say hello world:}",
            "",
            "    ```${7:csharp}",
            "    ${8:using System;",
            "",
            "    namespace HelloWorld",
            "    {",
            "        class Program",
            "        {",
            "            static void Main(string[] args)",
            "            {",
            "                Console.WriteLine(\"Hello, World!\");",
            "            }",
            "        }",
            "    }}",
            "    ```",
            "$0"
        ],
        "description": "multi-language tabbed code blocks"
    },
    "Table": {
        "scope": "markdown",
        "prefix": "Table",
        "body": [
            "| ${1:Product}      | ${2:What}                                 | ${3:Link} |",
            "| :----------- | :----------------------------------- | :--- |",
            "| ${4:`GET`}        | ${5::material-check:     Fetch resource}  | ${6:<>}   |",
            "| ${7:`PUT`}        | ${8::material-check-all: Update resource} | ${9:<>}   |",
            "| ${10:`DELETE`}     | ${11::material-close:     Delete resource} | ${12:<>}   |",
            "$0"
        ],
        "description": "markdown table with icons"
    },
    "Image (Centered with Caption)": {
        "scope": "markdown",
        "prefix": "Image (Centered)",
        "body": [
            "<figure>",
            "  <img src=\"${1:https://dummyimage.com/600x400/eee/aaa}\" width=\"${2:300}\" />",
            "  <figcaption>${3:Image caption}</figcaption>",
            "</figure>",
            "$0"
        ],
        "description": "centered image with caption"
    },
    "Nav Config (.nav.yml)": {
        "scope": "yaml",
        "prefix": "Nav Config Yaml",
        "body": [
            "title: ${1:Lorem Ipsum} # Custom title for .nav.yml root directory",
            "hide: ${2:false} # Hides .nav.yml root directory",
            "ignore: \"${3:*.hidden.md}\" # Hides pattern for files matching",
            "append_unmatched: ${4:true} # Anything that isn't explicitly caught will go to end",
            "",
            "sort:",
            "  direction: ${5:asc}",
            "  type: ${6:natural}",
            "  by: ${7:title} # some gotchas, read documentation",
            "  sections: ${8:last}",
            "  ignore_case: ${9:true}",
            "",
            "nav:",
            "  - ${10:one-i-want-first.md}",
            "  - \"*\" # the remaining files before directories and sections",
            "  - ${11:Custom Title: Directory}",
            "  - ${12:Custom Title: File.md}",
            "$0"
        ],
        "description": "mkdocs awesome-pages .nav.yml configuration"
    }
}