Skip to content

MkDocs#

I use MkDocs + MkDocs Material to document, which is what generated this site. Link

I find the following features to be great:

  • Free and Open Source Software
  • Statically Generated
  • Fairly Sane Theme Defaults
  • Fast Content Search Engine
  • Autolinking (Keeps links to pages alive even after moving)
  • Powerful Syntax Highlighting
  • Linkable Content Tabs (Multiple Programming Language / OS Options)
  • Admonition
  • RSS
  • Auto-Date Tracking
  • Multilingual Support
  • Multi-Version Support
  • All paid features are now free. link

I have a few dislikes:

  • mkdocs-material is in final release with an end-of-support in Nov 2026.
  • The mkdocs-material theme struggles with 50% split 1080p views. I have fixed this.

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

MkDocs Templates#

Title Metadata:

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

Blog Metadata:

---
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>

Warning:

!!! warning
    This will appear as a warning.

Note, Collapsed and Inline End w/ Custom Name:

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

Success, No title Box:

!!! success ""
    RESULT
Double code:

Emojis

Official List

Highlight code w/ Line Numbering:

```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 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]
```

Multi-OS Selection:

=== "Windows"

    Windows way:

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

=== "Ubuntu Linux"

    Another way to say hello world:

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

Multi-Language:

=== "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!")
    ```

Table:

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

Centered Image + Caption:

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

.nav.yml

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

Cards: Link

Common Variants & References:#

<> Thing Hi!