Skip to content

Ledger theme for MkDocs

This site is both a documentation and a showcase for this theme.

Getting started

Just follow the following steps.

Installation

Just install mkdocs-ledger from the GemFury repository (this requires credentials). Properly chose the extra depending on what you want to document:

# Basic installation
pip install mkdocs-ledger
# Installation with docstring support
pip install mkdocs-ledger[docstrings]
# Installation with `click` documentation support
pip install mkdocs-ledger[click]
# Installation with ADR support
pip install mkdocs-ledger[adr]
# Installation with all features
pip install mkdocs-ledger[docstrings,click,adr]

Configure mkdocs

Just use the ledger theme in your mkdocs.yml configuration:

theme: ledger

For docstrings support, use the mkdocstrings plugin. For click support, use the mkdocs-click plugin.

theme: ledger

markdown_extensions:
  - mkdocs-click

plugins:
  - material/search
  - mkdocstrings

Note

If you override plugins, you need to put every provided plugins, including material/search.

Detailed mkdocstrings configuration

In order to have a shiny docstring reference, you may use the following configuration:

  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          import:
            # Add used libs for external cross-references
            - https://docs.python.org/3/objects.inv
          paths: [src]
          options:
            docstring_options:
              ignore_init_summary: true
            docstring_section_style: list
            filters: ["!^_"]
            heading_level: 1
            inherited_members: true
            merge_init_into_class: true
            parameter_headings: true
            separate_signature: true
            show_docstring_modules: true
            show_if_no_docstring: true
            show_root_heading: true
            show_root_full_path: true
            show_signature_annotations: true
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            signature_crossrefs: true
  - gen-files:
      scripts:
      - scripts/doc.py
  - literate-nav:
      nav_file: SUMMARY.md

And in scripts/doc.py:

from ledger.mkdocs.docstrings import generate_source_documentation

generate_source_documentation("reference", "src/package")

Github Alerts

To enable support for GitHub Alerts, you need to enable the GitHub Callouts extension.

markdown_extensions:
  - github-callouts

ADR (Architecture Decision Records)

This theme includes tools for creating and managing ADRs (also known as MADRs) using the MADR 4.0 template.

To use ADR features, install with the adr extra:

pip install mkdocs-ledger[adr]

The package provides: - A CLI tool (adr) for creating and listing ADRs - An MkDocs plugin that automatically generates an ADR index page - Custom templates for rendering ADR pages

For more information, see: - MADR template documentation - ADR documentation

CLI Usage

The CLI is available as adr command and can be used directly or mounted as a PDM script.

# Create a new ADR
adr new --title "Use PostgreSQL Database" --status accepted

# List existing ADRs
adr list

# Get help
adr --help

To mount as a PDM script in your pyproject.toml:

[tool.pdm.scripts]
adr = {call = "ledger.mkdocs.adr:cli"}

MkDocs Integration

Add the plugin to your mkdocs.yml:

plugins:
  - adr:
      path: adr  # relative to docs_dir, defaults to "adr"

References

This theme is based on MkDocs and some extensions so please consult upstream documentations:

Showcase

Demo pages

The following pages are just here to showcase supported features:

  • docstrings: showcase docstrings support
  • OpenAPI: showcase OpenAPI documentation based on redoc/RedocLy
  • Click: showcase click automatic documentation
  • Mermaid: showcase mermaid.js diagrams integration
  • ADRs: showcase ADR (Architecture Decision Records) support

They are using fake or demo data, most of the time took form their feature official website. If you are hacking this theme, don't hesitarte to use those pages to see the result. If you add support for a specific feature, please add a page showcasing it.

ADR Support

This theme includes built-in support for Architecture Decision Records (ADRs), also known as Markdown Architectural Decision Records (MADRs).

ADRs are documents that capture important architectural decisions made for a project, along with their context and consequences. This theme provides:

  • A CLI tool for creating and listing ADRs
  • An MkDocs plugin that automatically generates an ADR index page
  • Custom templates for rendering ADR pages with the MADR 4.0 format

See the ADR showcase for examples, and refer to the MADR documentation for more details on the ADR format.

Light/Dark mode

This theme comes with support for both light and dark mode so don't forget to try both.

The toggle button (/) is in the top header on the right.