Python MkDocs

Static site generator that creates fast, simple documentation from Markdown files.

Overview

MkDocs is a fast, simple and lightweight static site generator designed specifically for building project documentation. It uses Markdown for content creation, making it accessible and easy to write. Documentation source files are configured with a single YAML file, and MkDocs builds completely static HTML sites that can be hosted anywhere. It features built-in development server with live reload, multiple themes including Material for MkDocs, and extensive plugin ecosystem for added functionality.

flowchart TB
    subgraph "Documentation Sources"
        A[Markdown Files] --> B[MkDocs Build]
        C[mkdocs.yml Config] --> B
        D[Custom Theme/CSS] --> B
        E[Plugins] --> B
    end

    subgraph "Build Process"
        B --> F[Parse Markdown]
        F --> G[Apply Theme]
        G --> H[Process Plugins]
        H --> I[Generate Static HTML]
    end

    subgraph "Output"
        I --> J[site/ Directory]
        J --> K[HTML Files]
        J --> L[CSS/JS Assets]
        J --> M[Search Index]
    end

    subgraph "Deployment"
        K --> N[GitHub Pages]
        K --> O[Read the Docs]
        K --> P[Static Hosting]
    end

Project Setup and Configuration

Key Concepts

mkdocs.yml: Single YAML configuration file for the entire project
docs/: Directory containing Markdown documentation files
site/: Generated static HTML output directory
index.md: Homepage of the documentation
Navigation: Defined in mkdocs.yml or auto-generated from file structure

Installing MkDocs

# Install MkDocs
uv pip install mkdocs

# Install with Material theme
uv pip install mkdocs-material

# Verify installation
mkdocs --version

# Get help
mkdocs --help

Creating a New Project

# Create new MkDocs project
mkdocs new my-project
cd my-project

# Project structure created:
# my-project/
# ├── docs/
# │   └── index.md
# └── mkdocs.yml

# Start development server
mkdocs serve

# Open browser at http://127.0.0.1:8000

Basic Project Structure

my-project/
├── mkdocs.yml          # Configuration file
├── docs/               # Documentation source
│   ├── index.md        # Homepage
│   ├── user-guide/     # Organised sections
│   │   ├── installation.md
│   │   └── getting-started.md
│   ├── api/
│   │   └── reference.md
│   ├── assets/         # Images, CSS, JS
│   │   ├── images/
│   │   ├── stylesheets/
│   │   └── javascripts/
│   └── about.md
├── site/               # Generated output (git ignored)
└── requirements.txt    # Python dependencies

Basic Configuration

# mkdocs.yml - Essential settings

# Project information
site_name: My Project Documentation
site_url: https://example.com
site_author: Your Name
site_description: Comprehensive documentation for My Project

# Repository
repo_name: username/repo
repo_url: https://github.com/username/repo
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright &copy; 2024 Your Name

# Navigation structure
nav:
  - Home: index.md
  - User Guide:
      - Installation: user-guide/installation.md
      - Getting Started: user-guide/getting-started.md
      - Configuration: user-guide/configuration.md
  - API Reference: api/reference.md
  - About: about.md

# Theme configuration
theme:
  name: material
  language: en

# Markdown extensions
markdown_extensions:
  - admonition
  - pymdownx.highlight:      # Use instead of codehilite with Material theme
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - toc:
      permalink: true

# Extra configuration
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username

Advanced Configuration

# mkdocs.yml - Comprehensive configuration

site_name: Advanced Project Docs
site_url: https://docs.example.com
site_author: Development Team
site_description: >-
  Comprehensive documentation covering installation,
  usage, API reference, and development guides.

# Repository settings
repo_name: org/repository
repo_url: https://github.com/org/repository
edit_uri: edit/main/docs/
edit_uri_template: 'edit/main/docs/{path}'

# Build directories
docs_dir: docs
site_dir: site

# Copyright and legal
copyright: >
  Copyright &copy; 2024 Your Company -
  <a href="#privacy">Privacy Policy</a>

# Theme configuration
theme:
  name: material
  language: en

  # Colour palette
  palette:
    # Light mode
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

  # Fonts
  font:
    text: Roboto
    code: Roboto Mono

  # Icons and logo
  logo: assets/logo.png
  favicon: assets/favicon.ico
  icon:
    repo: fontawesome/brands/github

  # Features
  features:
    - navigation.instant       # Instant loading
    - navigation.tracking      # URL updates with scroll
    - navigation.tabs          # Top-level tabs
    - navigation.tabs.sticky   # Sticky tabs
    - navigation.sections      # Section index pages
    - navigation.expand        # Expand subsections
    - navigation.indexes       # Section index pages
    - navigation.top           # Back to top button
    - toc.follow              # TOC follows scroll
    - toc.integrate           # Integrate TOC with nav
    - search.suggest          # Search suggestions
    - search.highlight        # Highlight search terms
    - search.share            # Share search results
    - header.autohide         # Auto-hide header
    - content.code.copy       # Copy button for code
    - content.code.annotate   # Code annotations
    - content.tabs.link       # Link content tabs

# Markdown extensions
markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      toc_depth: 3

  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Plugins
plugins:
  - search:
      lang: en
      separator: '[\s\-\.]+'
  - tags
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
  - git-revision-date-localized:
      enable_creation_date: true
      type: date

# Extra configuration
extra:
  # Analytics
  analytics:
    provider: google
    property: G-XXXXXXXXXX

  # Social links
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/org
      name: GitHub
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/handle
      name: Twitter
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/company/name
      name: LinkedIn

  # Version selector
  version:
    provider: mike
    default: stable

  # Consent (GDPR)
  consent:
    title: Cookie consent
    description: >-
      We use cookies to recognize your repeated visits and preferences,
      as well as to measure the effectiveness of our documentation.

# Additional CSS and JavaScript
extra_css:
  - assets/stylesheets/extra.css

extra_javascript:
  - assets/javascripts/extra.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

# Validation
validation:
  nav:
    omitted_files: warn
    not_found: warn
    absolute_links: warn
  links:
    not_found: warn
    absolute_links: warn
    unrecognized_links: warn

# Development server
dev_addr: 127.0.0.1:8000
use_directory_urls: true
strict: false

Navigation Configuration

# mkdocs.yml - Different navigation patterns

# Explicit navigation with sections
nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quickstart.md
      - Tutorial: getting-started/tutorial.md
  - User Guide:
      - Overview: user-guide/index.md
      - Configuration: user-guide/configuration.md
      - Advanced Usage: user-guide/advanced.md
  - API Reference:
      - Overview: api/index.md
      - Authentication: api/auth.md
      - Endpoints: api/endpoints.md
  - Development:
      - Contributing: development/contributing.md
      - Testing: development/testing.md
  - About:
      - Release Notes: about/release-notes.md
      - License: about/license.md

# Using section index pages
nav:
  - Home: index.md
  - User Guide:
      - user-guide/index.md  # Section overview
      - Installation: user-guide/installation.md
      - Configuration: user-guide/configuration.md

# Flat navigation
nav:
  - index.md
  - installation.md
  - configuration.md
  - api-reference.md
  - contributing.md

# Mixed explicit and auto-generated
# Omit 'nav' entirely for full auto-generation from file structure

Markdown Syntax and Features

Key Concepts

Standard Markdown: Headings, lists, links, images, code blocks
Extensions: Enhanced features via PyMdown Extensions
Admonitions: Callout boxes for notes, warnings, tips
Code highlighting: Syntax highlighting with line numbers and emphasis
Tabs and details: Interactive content elements

flowchart LR
    subgraph "Markdown Processing"
        A[Raw Markdown] --> B[Python Markdown]
        B --> C[Extensions]
        C --> D[Rendered HTML]
    end

    subgraph "Extensions"
        E[Admonition] --> C
        F[CodeHilite] --> C
        G[PyMdown] --> C
        H[TOC] --> C
    end

Headings and Structure

# H1 - Page Title

## H2 - Main Section

### H3 - Subsection

#### H4 - Sub-subsection

##### H5 - Minor Section

###### H6 - Smallest Heading

---

Horizontal rule for section breaks.

Text Formatting

# Basic formatting
*Italic text* or _italic text_
**Bold text** or __bold text__
***Bold and italic*** or ___bold and italic___

# Strikethrough (requires pymdownx.tilde)
~~Strikethrough text~~

# Superscript and subscript (requires pymdownx.caret/tilde)
H~2~O (subscript)
x^2^ (superscript)

# Highlighting (requires pymdownx.mark)
==Highlighted text==

# Keyboard keys (requires pymdownx.keys)
Press ++ctrl+alt+delete++ to restart.
Press ++cmd+c++ to copy.

# Smart symbols (requires pymdownx.smartsymbols)
(c) (r) (tm)
--> <-- <--> =/=
1st 2nd 3rd

Links and References

# Inline links
[Link text](https://example.com)
[Link with title](https://example.com "Title text")

# Reference links
[Link text][reference]
[Another link][ref2]

[reference]: https://example.com
[ref2]: https://example.com "Title"

# Auto-links
<https://example.com>
<email@example.com>

# Internal links
[Installation](user-guide/installation.md)
[API Reference](../api/reference.md)

# Link to heading
[Go to section](#heading-id)

# Link with anchor
[Specific section](page.md#section-name)

# Abbreviations (requires abbr extension)
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Lists

# Unordered lists
- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
    - Deeply nested 2.2.1
- Item 3

# Or with asterisks
* Item A
* Item B

# Or with plus
+ Item X
+ Item Y

# Ordered lists
1. First item
2. Second item
   1. Nested item
   2. Another nested
3. Third item

# Task lists (requires pymdownx.tasklist)
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
  - [x] Nested completed
  - [ ] Nested incomplete

# Definition lists (requires def_list extension)
First Term
:   Definition of first term

Second Term
:   First definition of second term
:   Second definition of second term

Code Blocks

# Inline code
Use the `print()` function to output text.

# Fenced code blocks with syntax highlighting
```python
def hello_world():
    """Print a greeting."""
    print("Hello, World!")
    return True

result = hello_world()

With line numbers (requires pymdownx.highlight)

def calculate_sum(a, b):
    total = a + b
    return total

With line highlighting

def example():
    important_line = "This is highlighted"
    another_important = "This too"
    normal_line = "Not highlighted"

With title

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

With line numbers starting at specific number

def function_at_line_10():
    pass

Code annotations (requires pymdownx.superfences)

theme:
  features:
    - navigation.tabs  # (1)!

1. Enable top-level navigation tabs

### Tables

```markdown
# Basic table
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |

# With alignment
| Left aligned | Center aligned | Right aligned |
| :----------- | :------------: | ------------: |
| Left         | Center         | Right         |
| Text         | Text           | Text          |

# Compact syntax
First Header | Second Header
------------ | -------------
Content Cell | Content Cell
Content Cell | Content Cell

# Complex tables with HTML (requires md_in_html)
<div markdown="1">

| Feature | Status | Notes |
|---------|--------|-------|
| Feature A | ✓ | Completed |
| Feature B | ⚠ | In Progress |

</div>

Images

# Basic image
![Alt text](path/to/image.png)

# With title
![Alt text](path/to/image.png "Image title")

# With sizing (requires attr_list)
![Alt text](image.png){ width="300" }
![Alt text](image.png){ width="50%" }

# With alignment
![Alt text](image.png){ align=left }
![Alt text](image.png){ align=right }

# With caption (using HTML)
<figure markdown>
  ![Image title](image.png){ width="400" }
  <figcaption>Image caption goes here</figcaption>
</figure>

# Clickable image
[![Alt text](thumbnail.png)](full-size.png)

# Image from URL
![Remote image](https://example.com/image.png)

Admonitions

# Basic admonition
!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

!!! danger
    This is a danger admonition.

# With custom title
!!! note "Custom Title"
    Custom title for the note.

# Collapsible admonition
??? info "Click to expand"
    This content is initially collapsed.

# Expanded collapsible
???+ tip "Click to collapse"
    This content is initially expanded.

# Available types
!!! note
!!! abstract
!!! info
!!! tip
!!! success
!!! question
!!! warning
!!! failure
!!! danger
!!! bug
!!! example
!!! quote

# Nested admonitions
!!! note
    Outer note.

    !!! warning
        Nested warning inside note.

# Inline content
!!! info inline end
    This appears on the right side.

Regular text flows around the inline admonition.

Tabs

# Content tabs (requires pymdownx.tabbed)
=== "Tab 1"
    Content for tab 1.

    ```python
    print("Tab 1 code")
    ```

=== "Tab 2"
    Content for tab 2.

    ```javascript
    console.log("Tab 2 code");
    ```

=== "Tab 3"
    Content for tab 3.

# Nested tabs
=== "Python"
    === "Example 1"
        ```python
        print("First example")
        ```

    === "Example 2"
        ```python
        print("Second example")
        ```

=== "JavaScript"
    ```javascript
    console.log("JavaScript example");
    ```

# Linked tabs (synchronized across page)
=== "Linux"
    Linux installation instructions.

=== "macOS"
    macOS installation instructions.

=== "Windows"
    Windows installation instructions.

Details and Summary

# Collapsible details (requires pymdownx.details)
<details>
  <summary>Click to expand</summary>
  Hidden content that can be revealed.
</details>

# With markdown content
<details markdown>
  <summary>Technical Details</summary>

  - Point 1
  - Point 2

  ```python
  code_example()

</details>

Using admonition syntax

??? note "Optional Details" This is collapsible content using admonition syntax.

### Mathematical Notation

```markdown
# Inline math (requires pymdownx.arithmatex)
The equation $E = mc^2$ is famous.

# Display math
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

# Complex equations
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

# Aligned equations
$$
\begin{align}
a &= b + c \\
  &= d + e + f
\end{align}
$$

Diagrams with Mermaid

# Mermaid diagrams (requires pymdownx.superfences)
```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Flowchart

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[Phone]
    C -->|Three| F[Car]

Sequence diagram

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob
    B->>A: Hello Alice
    A->>B: How are you?
    B->>A: Fine, thanks!

Class diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog

State diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Complete: Success
    Processing --> Error: Failure
    Complete --> [*]
    Error --> Idle: Retry

Gantt chart

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Task 1      :2024-01-01, 30d
    Task 2      :2024-01-15, 20d
    section Phase 2
    Task 3      :2024-02-01, 25d

Pie chart

pie title Language Usage
    "Python" : 45
    "JavaScript" : 30
    "Go" : 15
    "Rust" : 10

### Footnotes

```markdown
# Footnotes (requires footnotes extension)
This is a sentence with a footnote.[^1]

Another sentence with a footnote.[^note]

[^1]: This is the footnote text.

[^note]: This is another footnote with a reference name.

    Footnotes can have multiple paragraphs.

Theming and Customisation

Key Concepts

Built-in themes: mkdocs, readthedocs
Material theme: Most popular, feature-rich third-party theme
Custom CSS: Override styles with extra stylesheets
Theme configuration: Extensive options for colours, fonts, features
Templates: Override or extend theme templates

Built-in Themes

# mkdocs.yml - Default theme
theme:
  name: mkdocs
  # or
  name: readthedocs

# Configure navigation for built-in themes
theme:
  name: mkdocs
  highlightjs: true
  hljs_languages:
    - yaml
    - python
    - javascript
  navigation_depth: 3
  shortcuts:
    help: 191    # ?
    next: 78     # n
    previous: 80 # p
    search: 83   # s

Material Theme

# Install Material theme
uv pip install mkdocs-material

# Install with all extensions
uv pip install "mkdocs-material[imaging,git]"

# mkdocs.yml - Material theme configuration
theme:
  name: material

  # Colour scheme
  palette:
    # Single colour scheme
    scheme: default
    primary: indigo
    accent: indigo

  # Or with toggle between light/dark
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: blue
      accent: blue
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue
      accent: blue
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

  # Custom colours
  palette:
    scheme: default
    primary: custom  # Define in CSS
    accent: custom

  # Fonts
  font:
    text: Roboto
    code: Roboto Mono
    # Or use system fonts
    text: false
    code: false

  # Logo and icons
  logo: assets/logo.svg
  favicon: assets/favicon.png
  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye

  # Features (extensive list)
  features:
    # Navigation
    - navigation.instant        # XHR instant loading
    - navigation.instant.prefetch  # Prefetch pages
    - navigation.instant.progress  # Progress indicator
    - navigation.tracking       # URL updates on scroll
    - navigation.tabs          # Top-level tabs
    - navigation.tabs.sticky   # Sticky tabs on scroll
    - navigation.sections      # Render as sections
    - navigation.expand        # Expand subsections by default
    - navigation.path          # Show breadcrumbs
    - navigation.prune         # Reduce navigation size
    - navigation.indexes       # Section index pages
    - navigation.top           # Back to top button
    - navigation.footer        # Previous/next in footer

    # Table of contents
    - toc.follow              # TOC follows scroll
    - toc.integrate           # Integrate TOC into nav

    # Search
    - search.suggest          # Search suggestions
    - search.highlight        # Highlight search terms
    - search.share            # Share search link

    # Header
    - header.autohide         # Auto-hide header on scroll
    - announce.dismiss        # Dismissible announcements

    # Content
    - content.code.copy       # Copy button on code blocks
    - content.code.annotate   # Code annotations (# (1))
    - content.code.select     # Select code blocks
    - content.tabs.link       # Link content tabs
    - content.tooltips        # Improved tooltips
    - content.action.edit     # Edit page link
    - content.action.view     # View source link

# Language and direction
theme:
  language: en  # Language code
  direction: ltr  # Text direction: ltr or rtl

# Custom directories
theme:
  name: material
  custom_dir: overrides  # Custom template overrides
  static_templates:
    - 404.html

Material Colour Schemes

# mkdocs.yml - Available colour schemes

# Primary colours:
# red, pink, purple, deep purple, indigo, blue, light blue,
# cyan, teal, green, light green, lime, yellow, amber, orange,
# deep orange, brown, grey, blue grey, black, white

# Accent colours:
# red, pink, purple, deep purple, indigo, blue, light blue,
# cyan, teal, green, light green, lime, yellow, amber, orange,
# deep orange

# Scheme options:
theme:
  palette:
    scheme: default  # Light mode
    # or
    scheme: slate    # Dark mode

Custom CSS

# mkdocs.yml - Add custom stylesheets
extra_css:
  - assets/stylesheets/extra.css
  - assets/stylesheets/custom.css

/* docs/assets/stylesheets/extra.css */

/* Custom colour variables (Material theme) */
:root {
  --md-primary-fg-color: #3f51b5;
  --md-primary-fg-color--light: #5c6bc0;
  --md-primary-fg-color--dark: #303f9f;
  --md-accent-fg-color: #ff4081;
}

/* Dark mode colours */
[data-md-color-scheme="slate"] {
  --md-primary-fg-color: #5c6bc0;
  --md-accent-fg-color: #ff80ab;
}

/* Custom heading styles */
.md-content h1 {
  color: var(--md-primary-fg-color);
  border-bottom: 2px solid var(--md-primary-fg-color);
  padding-bottom: 0.3em;
}

.md-content h2 {
  color: var(--md-primary-fg-color--dark);
  margin-top: 2em;
}

/* Custom code block styling */
.md-typeset pre > code {
  border-left: 4px solid var(--md-accent-fg-color);
}

/* Custom admonition styling */
.md-typeset .admonition {
  border-left: 4px solid var(--md-accent-fg-color);
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

/* Custom table styling */
.md-typeset table:not([class]) {
  border: 1px solid var(--md-default-fg-color--lightest);
  border-radius: 4px;
}

.md-typeset table:not([class]) th {
  background-color: var(--md-primary-fg-color);
  color: white;
  font-weight: 600;
}

/* Custom button styles */
.md-button {
  border-radius: 4px;
  padding: 0.625em 1.5em;
}

.md-button--primary {
  background-color: var(--md-primary-fg-color);
  color: white;
  border: none;
}

/* Responsive adjustments */
@media screen and (max-width: 76.1875em) {
  .md-nav--primary .md-nav__title {
    background-color: var(--md-primary-fg-color);
  }
}

/* Custom footer */
.md-footer {
  background-color: var(--md-primary-fg-color--dark);
}

/* Syntax highlighting customisation */
.highlight .k { color: #ff6b6b; }  /* Keywords */
.highlight .s { color: #51cf66; }  /* Strings */
.highlight .nf { color: #4dabf7; } /* Functions */

Custom JavaScript

# mkdocs.yml - Add custom JavaScript
extra_javascript:
  - assets/javascripts/extra.js
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js

// docs/assets/javascripts/extra.js

// Add custom functionality on page load
document.addEventListener('DOMContentLoaded', function() {
  // Add copy buttons to code blocks
  document.querySelectorAll('pre code').forEach(function(block) {
    const button = document.createElement('button');
    button.className = 'copy-button';
    button.textContent = 'Copy';

    button.addEventListener('click', function() {
      navigator.clipboard.writeText(block.textContent);
      button.textContent = 'Copied!';
      setTimeout(() => button.textContent = 'Copy', 2000);
    });

    block.parentNode.insertBefore(button, block);
  });

  // Add external link icons
  document.querySelectorAll('a[href^="http"]').forEach(function(link) {
    if (!link.hostname.includes(window.location.hostname)) {
      link.classList.add('external-link');
      link.setAttribute('target', '_blank');
      link.setAttribute('rel', 'noopener noreferrer');
    }
  });

  // Smooth scroll to anchors
  document.querySelectorAll('a[href^="#"]').forEach(function(anchor) {
    anchor.addEventListener('click', function(e) {
      e.preventDefault();
      const target = document.querySelector(this.getAttribute('href'));
      if (target) {
        target.scrollIntoView({ behavior: 'smooth' });
      }
    });
  });
});

// Initialise Mermaid diagrams
if (typeof mermaid !== 'undefined') {
  mermaid.initialize({
    startOnLoad: true,
    theme: 'default',
    securityLevel: 'loose'
  });
}

Custom Templates

overrides/
├── main.html                  # Base template override
├── partials/
│   ├── header.html           # Custom header
│   ├── footer.html           # Custom footer
│   └── content.html          # Custom content wrapper
└── 404.html                  # Custom 404 page

<!-- overrides/main.html - Extend base template -->
{% extends "base.html" %}

{% block announce %}
  <!-- Custom announcement bar -->
  <div class="custom-announcement">
    🎉 New version released! <a href="/release-notes">Read more</a>
  </div>
{% endblock %}

{% block content %}
  {{ super() }}
  <!-- Add custom content after main content -->
  <div class="custom-footer-content">
    <p>Additional information or call-to-action</p>
  </div>
{% endblock %}

{% block scripts %}
  {{ super() }}
  <!-- Add custom scripts -->
  <script src="{{ 'assets/javascripts/custom.js' | url }}"></script>
{% endblock %}

<!-- overrides/partials/footer.html - Custom footer -->
<footer class="md-footer">
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <!-- Copyright -->
      <div class="md-footer-copyright">
        {% if config.copyright %}
          <div class="md-footer-copyright__highlight">
            {{ config.copyright }}
          </div>
        {% endif %}

        <!-- Custom footer links -->
        <div class="custom-footer-links">
          <a href="/privacy">Privacy Policy</a> |
          <a href="/terms">Terms of Service</a> |
          <a href="/contact">Contact</a>
        </div>
      </div>

      <!-- Social links -->
      {% include "partials/social.html" %}
    </div>
  </div>
</footer>

<!-- overrides/404.html - Custom 404 page -->
{% extends "base.html" %}

{% block content %}
  <div class="md-content" data-md-component="content">
    <article class="md-content__inner md-typeset">
      <h1>404 - Page Not Found</h1>

      <p>
        Sorry, the page you're looking for doesn't exist or has been moved.
      </p>

      <p>
        <a href="{{ config.site_url }}" class="md-button md-button--primary">
          Go to Homepage
        </a>
      </p>

      <h2>Popular Pages</h2>
      <ul>
        <li><a href="/getting-started/">Getting Started</a></li>
        <li><a href="/user-guide/">User Guide</a></li>
        <li><a href="/api/">API Reference</a></li>
      </ul>
    </article>
  </div>
{% endblock %}

Building and Serving Documentation

Key Concepts

Development server: Live reload for local development
Build process: Generate static HTML site
Deployment: Host on GitHub Pages, Read the Docs, or any static host
CI/CD: Automated building and deployment
Versioning: Maintain multiple documentation versions

flowchart LR
    subgraph "Development"
        A[Edit Markdown] --> B[mkdocs serve]
        B --> C[Live Preview]
        C --> A
    end

    subgraph "Production"
        D[mkdocs build] --> E[site/ Directory]
        E --> F{Deploy}
        F --> G[GitHub Pages]
        F --> H[Read the Docs]
        F --> I[Netlify/Vercel]
        F --> J[S3/CDN]
    end

Development Server

# Start development server
mkdocs serve

# Custom address and port
mkdocs serve -a 0.0.0.0:8080

# Specific config file
mkdocs serve -f custom-mkdocs.yml

# Enable strict mode (warnings as errors)
mkdocs serve --strict

# Disable live reload
mkdocs serve --no-livereload

# Watch theme files for live reload (theme development)
mkdocs serve --watch-theme

# Watch additional directories (can be repeated)
mkdocs serve --watch docs --watch overrides

# Development server features:
# - Live reload on file changes
# - Automatic browser refresh
# - Built-in search
# - Validation and warnings
# - Fast incremental builds

Building Documentation

# Build documentation
mkdocs build

# Clean build (remove site/ directory first)
mkdocs build --clean

# Strict mode (fail on warnings)
mkdocs build --strict

# Custom site directory
mkdocs build --site-dir public

# Custom config file
mkdocs build -f custom-mkdocs.yml

# Verbose output
mkdocs build --verbose

# Quiet mode (minimal output)
mkdocs build --quiet

# Build statistics
mkdocs build --verbose | grep "Building"

Validation and Testing

# Validate configuration
mkdocs build --strict

# Check for broken links (with plugin)
uv pip install mkdocs-linkcheck
# Add to mkdocs.yml plugins: - linkcheck
mkdocs build

# Test locally before deploy
mkdocs serve --strict

# Validate navigation structure
# Check mkdocs.yml nav matches actual files

# Check for:
# - Broken internal links
# - Missing images
# - Invalid Markdown
# - Configuration errors
# - Plugin conflicts

GitHub Pages Deployment

# .github/workflows/docs.yml - GitHub Actions workflow
name: Deploy Documentation

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch all history for git-revision-date-localized

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install mkdocs-material
          pip install -r requirements.txt

      - name: Build documentation
        run: mkdocs build --strict

      - name: Deploy to GitHub Pages
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          cname: docs.example.com  # Optional custom domain

# Manual GitHub Pages deployment
mkdocs gh-deploy

# With clean build
mkdocs gh-deploy --clean

# Specific remote name
mkdocs gh-deploy --remote-name upstream

# Specific branch
mkdocs gh-deploy --remote-branch gh-pages

# Force push
mkdocs gh-deploy --force

# Add commit message
mkdocs gh-deploy --message "Update documentation [ci skip]"

# Deploy from CI
mkdocs gh-deploy --no-history

Read the Docs Configuration

# .readthedocs.yaml - RTD configuration
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  jobs:
    pre_build:
      - pip install mkdocs-material
    post_build:
      - echo "Build complete"

mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: true

python:
  install:
    - requirements: requirements.txt
    - method: pip
      path: .

formats:
  - pdf
  - epub

search:
  ranking:
    api/*: -1
  ignore:
    - 404.html

# requirements.txt - Documentation dependencies
mkdocs>=1.5.0
mkdocs-material>=9.0.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
mkdocs-minify-plugin>=0.7.0
pymdown-extensions>=10.0.0

Other Hosting Options

# Netlify deployment
# 1. Build command: mkdocs build
# 2. Publish directory: site

# Vercel deployment
# 1. Build command: mkdocs build
# 2. Output directory: site

# AWS S3 + CloudFront
mkdocs build
aws s3 sync site/ s3://my-bucket/docs/ --delete
aws cloudfront create-invalidation --distribution-id ID --paths "/*"

# Google Cloud Storage
mkdocs build
gsutil -m rsync -r -d site/ gs://my-bucket/docs/

# GitLab Pages (.gitlab-ci.yml)
pages:
  image: python:3.11
  script:
    - pip install mkdocs-material
    - mkdocs build --strict
    - mv site public
  artifacts:
    paths:
      - public
  only:
    - main

Multi-version Documentation

# Install mike for version management
uv pip install mike

# Deploy version
mike deploy 1.0 latest --update-aliases

# Deploy and set as default
mike deploy 2.0 latest --update-aliases --push
mike set-default latest --push

# List versions
mike list

# Delete version
mike delete 1.0 --push

# Serve locally with version selector
mike serve

# Configuration in mkdocs.yml
extra:
  version:
    provider: mike

# mkdocs.yml - Version configuration
extra:
  version:
    provider: mike
    default: stable

  # Version warning for old versions
  version:
    warning:
      enabled: true
      message: >-
        You're viewing documentation for an older version.
        <a href="/latest/">View latest</a>

Build Optimisation

# mkdocs.yml - Performance optimisations

# Minify output
plugins:
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true
      cache_safe: true

# Optimize images
plugins:
  - optimize:
      enabled: true
      cache: true
      cache_dir: .cache/plugins/optimize
      optimize_jpg:
        quality: 85
      optimize_png:
        quality: 85

# Enable caching for faster rebuilds
plugins:
  - search:
      cache: true
  - git-revision-date-localized:
      enable_creation_date: true
      cache: true

# Exclude unnecessary files
exclude_docs: |
  draft/
  templates/
  *.tmp
  *.bak

Common Extensions and Plugins

Key Concepts

Markdown extensions: Enhance Markdown syntax (PyMdown Extensions)
MkDocs plugins: Add functionality during build process
Search: Built-in full-text search with customisation
Social cards: Auto-generated preview images
Git integration: Show last update dates and contributors

Essential Markdown Extensions

# mkdocs.yml - Essential extensions
markdown_extensions:
  # Python Markdown built-in
  - abbr                        # Abbreviation definitions
  - admonition                  # Note/warning callouts
  - attr_list                   # Add HTML attributes to elements
  - def_list                    # Definition lists
  - footnotes                   # Footnote support
  - md_in_html                  # Markdown inside HTML
  - tables                      # Table support
  - toc:                        # Table of contents
      permalink: true           # Add permalink to headings
      permalink_title: Anchor link to this section
      toc_depth: 3              # Max heading depth

  # PyMdown Extensions
  - pymdownx.arithmatex:        # LaTeX math support
      generic: true
  - pymdownx.betterem:          # Better emphasis handling
      smart_enable: all
  - pymdownx.caret              # Superscript and insert
  - pymdownx.mark               # Highlighting
  - pymdownx.tilde              # Subscript and delete
  - pymdownx.critic             # Track changes
  - pymdownx.details            # Collapsible details
  - pymdownx.emoji:             # Emoji support
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:         # Code highlighting
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
      auto_title: true
      linenums: true
  - pymdownx.inlinehilite       # Inline code highlighting
  - pymdownx.keys               # Keyboard keys
  - pymdownx.magiclink:         # Auto-link URLs
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: username
      repo: repository
  - pymdownx.smartsymbols       # Smart symbols
  - pymdownx.snippets:          # Include file snippets
      check_paths: true
      base_path: docs
  - pymdownx.superfences:       # Enhanced code blocks
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:            # Content tabs
      alternate_style: true
      combine_header_slug: true
  - pymdownx.tasklist:          # Task lists
      custom_checkbox: true
      clickable_checkbox: false

Essential MkDocs Plugins

# Install popular plugins
uv pip install mkdocs-material
uv pip install mkdocs-git-revision-date-localized-plugin
uv pip install mkdocs-minify-plugin
uv pip install mkdocs-redirects
uv pip install mkdocs-macros-plugin
uv pip install mkdocs-awesome-pages-plugin
uv pip install mkdocs-section-index
uv pip install mkdocs-tags

# mkdocs.yml - Essential plugins
plugins:
  # Search (built-in)
  - search:
      lang: en
      separator: '[\s\-\.]+'
      prebuild_index: true
      indexing: 'full'  # or 'sections', 'titles'

  # Git revision dates
  - git-revision-date-localized:
      enable_creation_date: true
      type: date  # or iso_date, iso_datetime, timeago
      fallback_to_build_date: true
      exclude:
        - index.md

  # Minification
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

  # Redirects
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'
        'legacy/index.md': 'current/index.md'

  # Tags
  - tags:
      tags_file: tags.md

  # Awesome pages (auto navigation)
  - awesome-pages:
      filename: .pages
      collapse_single_pages: true
      strict: false

  # Section index
  - section-index

  # Macros (variables and custom functions)
  - macros:
      module_name: docs/macros
      include_dir: docs/snippets

Advanced Plugins

# Social cards (auto-generated preview images)
uv pip install "mkdocs-material[imaging]"

# PDF generation
uv pip install mkdocs-with-pdf

# Multiple language support
uv pip install mkdocs-static-i18n

# Blog support
uv pip install mkdocs-material-blog-plugin

# Privacy plugin (self-host external assets)
uv pip install mkdocs-material

# API documentation
uv pip install "mkdocstrings[python]"

# mkdocs.yml - Advanced plugins

plugins:
  # Social cards (Material for MkDocs)
  - social:
      cards: true
      cards_layout_options:
        background_color: "#3f51b5"
        color: "#ffffff"

  # PDF generation
  - with-pdf:
      author: Your Name
      copyright: Copyright © 2024
      cover: true
      cover_title: Project Documentation
      cover_subtitle: Complete Reference Guide
      output_path: pdf/document.pdf

  # Multiple languages
  - i18n:
      docs_structure: folder
      languages:
        - locale: en
          name: English
          build: true
          default: true
        - locale: es
          name: Español
          build: true
        - locale: fr
          name: Français
          build: true

  # API documentation with mkdocstrings
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            members_order: source
            heading_level: 2

  # Privacy (self-host external assets)
  - privacy:
      enabled: true
      cache: true
      cache_dir: .cache/plugins/privacy
      assets_fetch: true
      assets_fetch_dir: assets/external

  # Blog
  - blog:
      enabled: true
      blog_dir: blog
      post_dir: "{blog}/posts"
      post_date_format: medium
      archive: true
      categories: true

Using Macros and Variables

# mkdocs.yml - Define variables
extra:
  version: 2.0.0
  api_url: https://api.example.com
  support_email: support@example.com

<!-- Use variables in Markdown -->
Current version: {{ config.extra.version }}

API endpoint: {{ config.extra.api_url }}

Contact us: {{ config.extra.support_email }}

Site name: {{ config.site_name }}

<!-- Custom macros -->
{% raw %}
{{ define_env() }}
{% endraw %}

# docs/macros.py - Custom macro functions

def define_env(env):
    """Define custom macros and filters."""

    @env.macro
    def code_example(language, code):
        """Create a formatted code example."""
        return f"```{language}\n{code}\n```"

    @env.macro
    def api_endpoint(path, method="GET"):
        """Format API endpoint documentation."""
        base_url = env.variables.get('api_url', 'https://api.example.com')
        return f"**{method}** `{base_url}{path}`"

    @env.filter
    def upper(text):
        """Convert text to uppercase."""
        return text.upper()

    # Add custom variables
    env.variables['project_version'] = '2.0.0'
    env.variables['build_date'] = '2024-01-15'

Using Snippets

# mkdocs.yml - Configure snippets
markdown_extensions:
  - pymdownx.snippets:
      check_paths: true
      base_path: docs
      auto_append:
        - includes/abbreviations.md

<!-- docs/snippets/installation.md -->
```bash
pip install mypackage

--8<-- "snippets/installation.md"

--8<-- "snippets/configuration.md:10:20"

### Using Tags

```yaml
# mkdocs.yml - Enable tags
plugins:
  - tags:
      tags_file: tags.md  # Page to list all tags

extra:
  tags:
    Python: python
    API: api
    Tutorial: tutorial

---
tags:
  - Python
  - Tutorial
  - Getting Started
---

# Getting Started with Python

Content here...

Best Practices for Documentation

Key Concepts

Documentation structure: Logical organisation and navigation
Writing style: Clear, concise, scannable content
Search optimisation: Improve discoverability
Maintenance: Keep documentation up-to-date
Accessibility: Ensure documentation is accessible to all users

Documentation Structure

docs/
├── index.md                    # Homepage - overview and quick links
├── getting-started/           # Getting started guides
│   ├── index.md               # Overview
│   ├── installation.md        # Installation instructions
│   ├── quickstart.md          # Quick start tutorial
│   └── configuration.md       # Basic configuration
├── user-guide/                # Task-oriented guides
│   ├── index.md               # User guide overview
│   ├── authentication.md      # Authentication guide
│   ├── data-management.md     # Data management
│   ├── advanced-features.md   # Advanced features
│   └── troubleshooting.md     # Troubleshooting
├── tutorials/                 # Step-by-step tutorials
│   ├── index.md               # Tutorials overview
│   ├── beginner/              # Beginner tutorials
│   ├── intermediate/          # Intermediate tutorials
│   └── advanced/              # Advanced tutorials
├── api/                       # API reference
│   ├── index.md               # API overview
│   ├── authentication.md      # Auth endpoints
│   ├── resources.md           # Resource endpoints
│   └── webhooks.md            # Webhooks
├── development/               # Development documentation
│   ├── index.md               # Development overview
│   ├── setup.md               # Development setup
│   ├── contributing.md        # Contribution guidelines
│   ├── testing.md             # Testing guide
│   └── architecture.md        # Architecture overview
├── reference/                 # Reference material
│   ├── glossary.md            # Glossary of terms
│   ├── cli.md                 # CLI reference
│   └── configuration.md       # Configuration reference
├── about/                     # About section
│   ├── release-notes.md       # Release notes
│   ├── changelog.md           # Detailed changelog
│   ├── license.md             # License information
│   └── support.md             # Support information
└── assets/                    # Static assets
    ├── images/
    ├── stylesheets/
    └── javascripts/

Writing Quality Documentation

# Good documentation principles

## Installation

### Prerequisites

Before installing, ensure you have:

- Python 3.8 or higher
- pip 20.0 or higher
- Virtual environment (recommended)

Check your Python version:

```bash
python --version  # Should be 3.8+

Installation Steps

=== "pip" bash pip install mypackage

=== "pip (development)" bash pip install mypackage[dev]

=== "From source" bash git clone https://github.com/user/mypackage.git cd mypackage pip install -e .

Verify Installation

import mypackage

print(mypackage.__version__)
# Expected output: 2.0.0

!!! success "Installation Complete" You're now ready to use mypackage! Continue to [Quick Start](quickstart.md) →

Quick Start

Here's a minimal example:

from mypackage import Client

# Create client with API key
client = Client(api_key="your-api-key")

# Make a request
result = client.get_data()
print(result)

!!! tip Store your API key in environment variables: bash export API_KEY="your-api-key"

For detailed examples, see [Tutorials](../tutorials/index.md).

### Writing Style Guidelines

```markdown
# Documentation writing best practices

## Be Clear and Concise

❌ Bad:
"In order to facilitate the process of authenticating with the API,
you will need to obtain an API key from your account dashboard."

✅ Good:
"Get your API key from the account dashboard to authenticate."

## Use Active Voice

❌ Bad:
"The configuration file should be created by the user."

✅ Good:
"Create a configuration file."

## Write Scannable Content

✅ Good structure:
- Use headings to break up content
- Use bullet points for lists
- Use code blocks for examples
- Use admonitions for important notes
- Use tables for structured data

## Provide Context

❌ Bad:
```python
client.connect()

✅ Good:

# Connect to the database
# This establishes a connection pool with 10 connections
client.connect(max_connections=10)

Show Expected Output

✅ Good:

$ myapp --version
myapp version 2.0.0

Use Admonitions Appropriately

!!! note Additional information that's helpful but not critical.

!!! warning Important information about potential issues.

!!! danger Critical information about data loss or security.

!!! tip Helpful suggestions or best practices.

!!! example Practical examples demonstrating concepts.

### Navigation Best Practices

```yaml
# mkdocs.yml - Well-organised navigation

nav:
  - Home: index.md

  - Getting Started:
      - getting-started/index.md
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quickstart.md
      - Configuration: getting-started/configuration.md

  - User Guide:
      - user-guide/index.md
      - Authentication: user-guide/authentication.md
      - Data Management: user-guide/data-management.md
      - Advanced Features: user-guide/advanced-features.md
      - Troubleshooting: user-guide/troubleshooting.md

  - Tutorials:
      - tutorials/index.md
      - Beginner:
          - First Steps: tutorials/beginner/first-steps.md
          - Basic Operations: tutorials/beginner/basic-operations.md
      - Advanced:
          - Custom Integration: tutorials/advanced/custom-integration.md
          - Performance Optimisation: tutorials/advanced/performance.md

  - API Reference:
      - api/index.md
      - Authentication: api/authentication.md
      - Resources: api/resources.md
      - Webhooks: api/webhooks.md

  - Development:
      - development/index.md
      - Contributing: development/contributing.md
      - Testing: development/testing.md
      - Architecture: development/architecture.md

  - About:
      - Release Notes: about/release-notes.md
      - Changelog: about/changelog.md
      - License: about/license.md

# Principles:
# 1. Logical grouping (Getting Started, User Guide, API, etc.)
# 2. Progressive disclosure (simple to complex)
# 3. Clear, descriptive titles
# 4. Reasonable depth (max 3 levels)
# 5. Section index pages for overviews

Search Optimisation

---
title: Authentication Guide - Complete Tutorial
description: Learn how to authenticate with the API using API keys, OAuth, and JWT tokens
keywords: authentication, API keys, OAuth, JWT, security
---

# Authentication Guide

Learn how to authenticate with the API using various methods.

<!-- Use clear headings with keywords -->
## API Key Authentication

<!-- Use descriptive link text -->
See the [API key management guide](../user-guide/api-keys.md) for details.

<!-- Not: "Click [here](link)" -->

<!-- Use alt text for images -->
![Authentication flow diagram showing OAuth process](auth-flow.png)

<!-- Include synonyms and common terms -->
<!-- Authentication, authorisation, auth, login, credentials, tokens -->

# mkdocs.yml - Search configuration
plugins:
  - search:
      lang:
        - en
      separator: '[\s\-\.]+'
      prebuild_index: true
      indexing: 'full'  # Index full content

Accessibility Best Practices

# Accessibility guidelines

## Use Semantic Headings

✅ Good - proper heading hierarchy:
# Page Title (H1)
## Main Section (H2)
### Subsection (H3)
#### Detail (H4)

❌ Bad - skipping levels:
# Page Title (H1)
### Subsection (H3)  ← Skips H2

## Provide Alt Text for Images

✅ Good:
![Diagram showing the authentication flow with user, server, and database](auth-flow.png)

❌ Bad:
![](image.png)

## Use Descriptive Links

✅ Good:
Read the [installation guide](install.md)

❌ Bad:
Click [here](install.md)

## Provide Transcripts for Videos

<video src="tutorial.mp4" controls></video>

[Video transcript](transcript.md)

## Use Sufficient Colour Contrast

```css
/* Ensure text is readable */
.md-content {
  color: #333;  /* Dark grey on white */
  background: #fff;
}

Support Keyboard Navigation

All interactive elements should be keyboard accessible (tabs, enter, etc.)

Use ARIA Labels When Needed

<button aria-label="Close navigation menu">×</button>

### Version Documentation

```markdown
---
title: Release Notes - Version 2.0.0
---

# Release Notes

## Version 2.0.0 (2024-01-15)

### 🎉 New Features

- Added support for async operations
- Implemented webhook functionality
- New CLI commands for data export

### 🔧 Changes

- Updated authentication flow
- Improved error messages
- Changed default timeout from 30s to 60s

### 🐛 Bug Fixes

- Fixed memory leak in connection pool
- Resolved race condition in async handler
- Corrected timezone handling

### ⚠️ Breaking Changes

!!! danger "Breaking Changes"
    - Removed deprecated `old_method()` - use `new_method()` instead
    - Changed return type of `get_data()` from `dict` to `DataObject`
    - Minimum Python version is now 3.8

### 📚 Documentation

- Added new tutorials section
- Updated API reference
- Improved getting started guide

### Migration Guide

Upgrading from 1.x to 2.0:

```python
# Old (1.x)
result = client.old_method()

# New (2.0)
result = client.new_method()

See [Migration Guide](migration-guide.md) for full details.

Version 1.5.0 (2023-12-01)

...

### Maintenance and Updates

```markdown
# Documentation maintenance checklist

## Regular Updates

- [ ] Review and update outdated information
- [ ] Test all code examples
- [ ] Check and fix broken links
- [ ] Update version numbers
- [ ] Review and respond to feedback
- [ ] Update screenshots if UI changed

## Quality Checks

```bash
# Build with strict mode
mkdocs build --strict

# Check for broken links
mkdocs build --strict 2>&1 | grep -i "warning\|error"

# Spell check (with codespell)
codespell docs/

# Validate Markdown (with markdownlint)
markdownlint docs/**/*.md

Version Control

Keep documentation in same repository as code
Review documentation in pull requests
Use semantic versioning for docs
Tag documentation versions

Continuous Integration

# .github/workflows/docs-check.yml
name: Check Documentation

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install mkdocs-material
      - run: mkdocs build --strict

## Quick Reference

| Category | Command/Syntax | Description |
|----------|----------------|-------------|
| **Project** | `mkdocs new project` | Create new project |
| | `mkdocs serve` | Start dev server |
| | `mkdocs build` | Build static site |
| | `mkdocs gh-deploy` | Deploy to GitHub Pages |
| **Config** | `site_name:` | Project name |
| | `theme: material` | Use Material theme |
| | `nav:` | Define navigation |
| | `plugins:` | Enable plugins |
| **Markdown** | `# Heading` | H1 heading |
| | `**bold**` | Bold text |
| | `*italic*` | Italic text |
| | `` `code` `` | Inline code |
| | `[text](url)` | Link |
| | `![alt](img.png)` | Image |
| **Admonitions** | `!!! note` | Note callout |
| | `!!! warning` | Warning callout |
| | `??? info` | Collapsible info |
| | `???+` | Expanded by default |
| **Code** | ` ```python ` | Python code block |
| | `linenums="1"` | Show line numbers |
| | `hl_lines="2 3"` | Highlight lines |
| | `title="file.py"` | Code block title |
| **Tabs** | `=== "Tab 1"` | Create tabs |
| **Extensions** | `pymdownx.superfences` | Enhanced code blocks |
| | `pymdownx.tabbed` | Content tabs |
| | `pymdownx.emoji` | Emoji support |
| | `admonition` | Callout boxes |

## Common Issues and Solutions

| Issue | Solution |
|-------|----------|
| `Config file not found` | Run `mkdocs new .` or check `mkdocs.yml` location |
| Theme not found | Install theme: `uv pip install mkdocs-material` |
| Page not in navigation | Add page to `nav:` in `mkdocs.yml` or remove `nav:` for auto-generation |
| Images not displaying | Check path relative to Markdown file or use absolute path from `docs/` |
| Search not working | Rebuild with `mkdocs build --clean` |
| Code highlighting not working | Install Pygments: `uv pip install pygments` |
| Mermaid diagrams not rendering | Add `pymdownx.superfences` with mermaid fence configuration |
| Changes not reflected | Ensure dev server is running with `mkdocs serve` |
| Build fails with warnings | Run `mkdocs build --strict` to see detailed errors |
| Custom CSS not loading | Check file path in `extra_css` and ensure file exists |
| Slow build times | Disable unnecessary plugins or enable caching |
| `gh-deploy` fails | Ensure gh-pages branch exists and permissions are correct |
| Links broken after deploy | Use `use_directory_urls: true` in config |
| Math not rendering | Add MathJax JavaScript in `extra_javascript` |
| Plugin conflicts | Check plugin compatibility and load order |

## Related Topics

The following topics complement Python MkDocs documentation and would make excellent additions to your cheatsheet collection:

1. **Python Sphinx** - Alternative documentation generator with reStructuredText
2. **Python Markdown** - Deep dive into Markdown processing and extensions
3. **GitHub Pages** - Hosting platform for static documentation sites
4. **Read the Docs** - Documentation hosting with continuous deployment
5. **Python Packaging** - Integrating documentation with Python packages
6. **Static Site Generators** - Comparison of documentation tools (Hugo, Jekyll, etc.)