richdocs

A batteries-included documentation experience for MkDocs Material — Shiki syntax highlighting, runnable live code, API-symbol hover & auto-linking, mkdocstrings enum/decorator badges, and a polished collapsible TOC, all from a single plugin entry.

This site is itself built with richdocs.

One plugin, the whole experience

No hand-wiring extra_css, extra_javascript, or custom_templates. Add richdocs to plugins: and point it at your package.

Install

pip install richdocs

Quickstart

# mkdocs.yml
theme:
  name: material
  palette:
    scheme: slate

plugins:
  - search
  - richdocs:            # list BEFORE mkdocstrings
      package: your_package
  - mkdocstrings:
      handlers:
        python:
          paths: [src]

The plugin's configuration is the RichDocsPlugin entry point — see the API reference and the full configuration guide.

What you get

Highlighted codeRunnable live codeAuto-linked prose

from dataclasses import dataclass

@dataclass
class Widget:
    """A small widget."""
    size: int = 1

    def grow(self, by: int) -> "Widget":
        return Widget(self.size + by)

Click ▶ Run below — on this published site it executes in your browser via Pyodide (WebAssembly), no server needed. The first run downloads the Python runtime, so give it a few seconds.

import sys
print("hello from richdocs")
print("running", sys.version.split()[0], "in the browser via Pyodide")

Mentions of API symbols like RichDocsPlugin in prose become links to the reference automatically — no manual cross-references.

Highlights

• 🎨 VS Code-accurate Shades of Purple highlighting (Shiki), themeable.
• 🔗 Inline `Symbol` auto-linking + hover tooltips in code blocks.
• 🏷️ Enums render as enum / member; decorator badges in headings & TOC.
• 🧭 Scroll-spy + collapsible TOC tuned for long API pages.
• ⚙️ Typed, validated config — only package is required.