mkdocs-typer2 0.3.0

Typer CLI docs for MkDocs (optional) and Zensical via Python-Markdown

mkdocs-typer2

A Python-Markdown extension (and optional MkDocs plugin) that automatically generates documentation for your Typer CLI applications. The same extension works with Zensical using markdown_extensions only.

You might be wondering why there are two plugins for Typer. The mkdocs-typer plugin is great, but it hasn't been updated in over a year, and there have been a number of changes to Typer since then. One important change is that Typer now has its own documentation generation system via the typer <module> utils docs command. This plugin simply leverages that system to generate the documentation for your Typer CLIs.

I created this plugin because the original plugin was no longer working for me, and I wanted to have a simple plugin that would work with the latest version of Typer. If the original mkdocs-typer plugin still works for you, there probably isn't a reason to switch. However, if you are looking for a plugin that will work with the latest version of Typer, this plugin is for you!

• Read The Docs
• Check out a demo

Features

• Integrates with MkDocs (optional extra) and the Material theme, or with Zensical via Markdown extensions
• Automatically generates CLI documentation from your Typer commands
• Supports all Typer command features including arguments, options, and help text
• Easy to configure and use
• pretty feature for formatting arguments & options as tables
• engine option to select legacy markdown parsing or native Click walking
• Global plugin configuration or per-documentation block configuration

How It Works

The plugin can either parse Typer's generated markdown (legacy) or walk the Click command tree directly (native). Both approaches are rendered as Markdown and integrated into your MkDocs site.

The plugin works by:

1. Registering a Markdown extension that processes special directive blocks
2. Resolving the command tree (legacy: typer <module> utils docs, native: Click walk)
3. Formatting arguments and options as lists or tables based on pretty
4. Integrating the resulting HTML into the generated site

Installation

The base package installs the Typer CLI helper, the Python-Markdown extension (mkdocs_typer2.markdown:makeExtension), and runtime dependencies only. Add MkDocs and/or Zensical when you need them.

Markdown extension only (for example with Zensical, or if you register the extension yourself):

pip install mkdocs-typer2

With MkDocs (enables the mkdocs-typer2 plugin entry point):

pip install "mkdocs-typer2[mkdocs]"

With Zensical (installs the zensical CLI into the same environment; you still configure markdown_extensions as shown below):

pip install "mkdocs-typer2[zensical]"

Both:

pip install "mkdocs-typer2[mkdocs,zensical]"

Using uv:

uv add "mkdocs-typer2[mkdocs]"   # or [zensical] / [mkdocs,zensical]

Requirements

• Python 3.10 or higher
• Always: Typer 0.12.5 or higher, Pydantic 2.9.2 or higher, Python-Markdown 3.3.6 or higher (declared as markdown on PyPI)
• Optional: MkDocs 1.6.1 or higher (install extra [mkdocs])
• Optional: Zensical 0.0.30 or higher (install extra [zensical])

Configuration

MkDocs

Add the plugin to your mkdocs.yml file:

plugins:
  - mkdocs-typer2

Pretty Mode

The plugin offers a pretty option that can be set in your mkdocs.yml file to enable table-based formatting for options and arguments:

plugins:
  - mkdocs-typer2:
      pretty: true

Options when :pretty: false:

Options:

• --name: The name of the project [required]

Options when :pretty: true:

Name	Description	Required	Default
--name	The name of the project	Yes	-

Engine Selection

Use engine to select how the command tree is built:

plugins:
  - mkdocs-typer2:
      engine: native  # or legacy

Zensical

Zensical uses the same Python-Markdown stack as MkDocs for compatibility, so you enable this project as a Markdown extension only. Zensical does not run arbitrary MkDocs Python plugins, so do not list mkdocs-typer2 under plugins.

Install with pip install "mkdocs-typer2[zensical]" (or include zensical in your environment another way), then register the extension and options that match what you would pass to the MkDocs plugin.

mkdocs.yml (Zensical reads this format):

markdown_extensions:
  - tables
  - mkdocs_typer2.markdown:makeExtension:
      pretty: false
      engine: native

The tables extension is included here because the extension renders inner CLI markdown with markdown.markdown(..., extensions=["tables"]).

zensical.toml (quoted table key because the factory path contains a colon):

[project.markdown_extensions.tables]

[project.markdown_extensions."mkdocs_typer2.markdown:makeExtension"]
pretty = false
engine = "native"

If you share one project between MkDocs and Zensical, keep mkdocs-typer2 out of plugins for the Zensical-focused config (or use separate config files) so the Markdown extension is not applied twice.

Usage

Basic Usage

In your Markdown files, use the ::: mkdocs-typer2 directive to generate documentation for your Typer CLI:

::: mkdocs-typer2
    :module: my_module
    :name: mycli

Required Parameters

• :module: - The module containing your Typer CLI application. This is the installed module, not the directory path. For example, if your app is located in src/my_module/cli.py, your :module: should typically be my_module.cli.

Optional Parameters

• :name: - The name of the CLI. If left blank, your CLI will simply be named CLI in your documentation.
• :pretty: - Set to true to enable pretty formatting for this specific documentation block, overriding the global setting.
• :engine: - legacy parses Typer markdown (deprecated). native walks Click and renders lists or tables based on pretty.

Advanced Usage

Per-Block Pretty Configuration

You can override the global pretty setting for individual documentation blocks:

::: mkdocs-typer2
    :module: my_module.cli
    :name: mycli
    :pretty: true
    :engine: native

Multiple CLI Documentation

You can document multiple CLIs in the same MkDocs site by using multiple directive blocks:

# Main CLI

::: mkdocs-typer2
    :module: my_module.cli
    :name: mycli

# Admin CLI

::: mkdocs-typer2
    :module: my_module.admin
    :name: admin-cli

Example

This repository is a good example of how to use the plugin. We have a simple CLI located in src/mkdocs_typer2/cli/cli.py.

The CLI's documentation is automatically generated using the block level directive in docs/cli.md:

::: mkdocs-typer2
    :module: mkdocs_typer2.cli.cli
    :name: mkdocs-typer2
    :engine: legacy

And the pretty versions in docs/cli-pretty-legacy.md and docs/cli-pretty-native.md:

::: mkdocs-typer2
    :module: mkdocs_typer2.cli.cli
    :name: mkdocs-typer2
    :pretty: true
    :engine: legacy

:::: mkdocs-typer2
    :module: mkdocs_typer2.cli.cli
    :name: mkdocs-typer2
    :pretty: true
    :engine: native

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

When working in this repository, sync dependencies (including optional extras used in CI) with:

uv sync --all-extras --group dev

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.