---

name: mkdocs description: >- MkDocs is a Python static site generator that builds a documentation site from Markdown files and one mkdocs.yml, most often with the Material for MkDocs theme. Use when a user asks to create project documentation, configure MkDocs themes, add search and navigation, customize Markdown extensions, deploy docs to GitHub Pages, version docs with mike, or decide between MkDocs 1.x, Material for MkDocs and its successor Zensical. license: Apache-2.0 compatibility: "Python 3.8+ for MkDocs 1.6 and Material for MkDocs 9.7; Python 3.10+ for Zensical" metadata: author: terminal-skills version: "1.1.0" category: development tags: ["documentation", "python", "static-site", "material-theme", "markdown"] repository: https://github.com/mkdocs/mkdocs

MkDocs — Python Documentation Generator

Overview

MkDocs turns a folder of Markdown files and one mkdocs.yml into a static documentation site. Most sites pair it with Material for MkDocs (mkdocs-material), which adds the theme, search, navigation features, tags, blog and social cards. The ecosystem changed in 2025–2026, so check the state before starting (as of October 2026):

• MkDocs 1.6.1 (August 2024) is still the latest stable release; pip install mkdocs installs it. There has been no 1.x release since.
• MkDocs 2.0 exists only as pre-releases (2.0.dev6, installed only with pip install --pre). It is a rewrite: according to the Material for MkDocs maintainers it drops the plugin system, replaces the theming API and does not read mkdocs.yml (2.0.dev6 stops with an error when it finds one), so no existing Material site builds on it.
• Material for MkDocs 9.7 is in maintenance mode since November 2025: 9.7.0 was the last feature release (it made the former Insiders features free), and the team promised critical bug and security fixes for at least 12 months, later extended to May 5, 2027, when the theme reaches end of life. It requires mkdocs>=1.6,<2.
• Zensical (zensical, MIT) is the successor from the same team. It reads an existing mkdocs.yml, reimplements the popular plugins natively and is released about once a week. It is at 0.0.67, a series its own team calls alpha; they have announced 0.1.0, the first release line they describe as dependable, for November 5, 2026.
• ProperDocs (properdocs) is a community fork of MkDocs 1.x that aims to be a drop-in replacement.

Instructions

What to use today

• Existing Material for MkDocs site: keep building it, with exact version pins. Nothing forces a move, but it will get no new features. Build the same mkdocs.yml with Zensical alongside and switch when every plugin you depend on is supported (Example 2).
• New site: start with Zensical if its supported plugin list covers you; pin the exact version because it is pre-1.0. Choose Material for MkDocs 9.7 if you need a third-party MkDocs plugin Zensical does not replace, and accept that it is frozen.
• Never install MkDocs with --pre or leave mkdocs unpinned in a Material project.

Setup

python3 -m venv .venv && source .venv/bin/activate
pip install "mkdocs-material==9.7.7"       # installs mkdocs 1.6.1
mkdocs new ledger-docs && cd ledger-docs   # creates mkdocs.yml and docs/index.md
mkdocs serve                               # live preview at http://127.0.0.1:8000
mkdocs build --strict                      # static site in site/; warnings fail the build
pip freeze > requirements.txt              # lock the versions for CI

Material prints a red notice about MkDocs 2.0 on every build; export NO_MKDOCS_2_WARNING=1 silences it.

Configuration

# mkdocs.yml
site_name: Ledger SDK Documentation
site_url: https://docs.ledgerkit.dev/
repo_url: https://github.com/ledgerkit/ledger-sdk
repo_name: ledgerkit/ledger-sdk

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant           # SPA-like navigation (needs site_url)
    - navigation.tracking          # URL follows the active heading
    - navigation.tabs              # top-level sections as tabs
    - navigation.sections
    - navigation.expand
    - navigation.top               # back-to-top button
    - search.suggest
    - search.highlight
    - content.code.copy            # copy button on code blocks
    - content.code.annotate        # code annotations
    - content.tabs.link            # linked content tabs
    - announce.dismiss

plugins:
  - search                         # must be listed again once `plugins` is set
  - tags
  - social                         # needs: pip install "mkdocs-material[imaging]"

markdown_extensions:
  - admonition                     # callout boxes
  - pymdownx.details               # collapsible callouts
  - pymdownx.superfences           # nested code blocks, Mermaid
  - pymdownx.tabbed:
      alternate_style: true        # content tabs
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started:
    - Installation: guide/installation.md
    - Quick Start: guide/quickstart.md
  - API Reference:
    - Client: api/client.md
  - Changelog: changelog.md

Markdown Features (Material Theme)

!!! note "Sandbox keys"
    Keys that start with `lk_test_` only reach the sandbox.

!!! warning
    This endpoint is rate limited to 60 requests per minute.

??? info "Click to expand"
    A collapsible admonition (`pymdownx.details`).

=== "Python"

    ```python
    client = Client(
        api_key=os.environ["LEDGER_API_KEY"],  # (1)!
        timeout=30,                            # (2)!
    )
    ```

    1. Create the key under Settings → API keys.
    2. Seconds. The default is 60.

=== "cURL"

    ```bash
    curl -H "Authorization: Bearer $LEDGER_API_KEY" https://api.ledgerkit.dev/v1/invoices
    ```

The (1)! markers are code annotations (content.code.annotate); the numbered list directly below the block supplies their text.

API reference, versions, deployment

pip install "mkdocstrings[python]"     # then add `- mkdocstrings` under plugins
pip install mike                       # versioned docs on the gh-pages branch
mike deploy --push --update-aliases 2.1 latest
mike set-default --push latest
mkdocs gh-deploy --force               # unversioned: build and push site/ to gh-pages

• A page containing ::: ledger_sdk.Client renders that class from its docstrings.
• For the version selector add extra: { version: { provider: mike } } to mkdocs.yml. Use either mike or mkdocs gh-deploy on a repository, not both.
• In CI, run the same commands after pip install -r requirements.txt with permissions: contents: write, and set the Pages source to the gh-pages branch.

Zensical

pip install "zensical==0.0.67"
zensical new handbook        # zensical.toml, docs/, .github/workflows/docs.yml
cd handbook
zensical serve               # preview at localhost:8000
zensical build --clean       # static site in site/

zensical build and zensical serve also run in a directory that only has mkdocs.yml. Not supported there: hooks, exclude_docs, draft_docs, not_in_nav, the gh-deploy and get-deps commands, and the --site-dir, --theme and --use-directory-urls flags (set them in the config). Plugins without a native replacement are skipped silently. theme: { variant: classic } keeps the Material look; the default is the new modern design.

Examples

Example 1: Documentation for a Python SDK, published on GitHub Pages

User: "Set up docs for our SDK with MkDocs Material and publish them from CI."

python3 -m venv .venv && source .venv/bin/activate
pip install "mkdocs-material[imaging]==9.7.7" "mkdocstrings[python]"
mkdocs new . && pip freeze > requirements.txt

Write the mkdocs.yml shown above with - mkdocstrings added to plugins, put ::: ledger_sdk.Client in docs/api/client.md, create the other pages listed under nav: (a missing one aborts a --strict build), then add the workflow:

# .github/workflows/docs.yml
name: docs
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs gh-deploy --force --strict

Result: mkdocs build --strict ends with INFO - Documentation built in 7.85 seconds; site/ contains index.html, api/client/index.html with the methods of Client, search/, sitemap.xml and one social card PNG per page under site/assets/images/social/. Each push to main updates the gh-pages branch.

Example 2: Try Zensical on an existing Material for MkDocs site

User: "Material for MkDocs is in maintenance mode. Can our docs move to Zensical?"

python3 -m venv .venv-zensical
.venv-zensical/bin/pip install "zensical==0.0.67" mkdocstrings-python
.venv-zensical/bin/zensical build --clean

Build started
No issues found
Build finished in 4.21s

Compare site/ with the MkDocs output page by page (navigation, search, tabs, annotations, API pages), and check every entry under plugins: against the supported list at https://zensical.org/docs/compatibility/mkdocs/plugins/. The same mkdocs.yml keeps building with mkdocs build, so the production pipeline stays untouched until the comparison is clean; then replace mkdocs gh-deploy in CI with zensical build --clean plus a GitHub Pages upload (the workflow zensical new generates shows the steps).

Guidelines

1. Pin everything — mkdocs-material==9.7.7 (or an exact zensical version) in requirements.txt; rebuild the lock file on purpose, not on every CI run
2. Build with --strict in CI — broken links and missing nav entries fail the build instead of shipping
3. Material theme — use mkdocs-material rather than the built-in mkdocs and readthedocs themes for search, tabs, annotations and dark mode
4. Code annotations — (1)! for inline explanations instead of long comments
5. Content tabs — show the same example in several languages; content.tabs.link keeps the choice across the page
6. Admonitions for callouts — !!! note/warning/tip/danger; more visible than bold text
7. Social cards — the social plugin needs the imaging extra plus the Cairo system library; a stale .cache/ can hide the missing dependency, so add .cache/ to .gitignore and install the extra in CI
8. Versioning — mike keeps each version in its own folder on gh-pages; with Zensical it works through the fork squidfunk/mike until native versioning ships
9. Third-party plugins are code — an MkDocs plugin and hooks: run arbitrary Python during the build; install only plugins you trust
10. When not to use — a site that needs React components or MDX is better served by Docusaurus; Sphinx remains the choice for reStructuredText and heavy cross-project API references