mkdocs-click

What it is and what it does

mkdocs-click is an MkDocs extension that introspects Click command-line applications and automatically generates formatted documentation for them. You point it at a Click command or group, and it produces Markdown with command descriptions, options, arguments, and subcommands—all embedded directly into your MkDocs site during the build. It handles nested commands, allows you to customize header depth and styling, and can optionally show full command paths and hidden commands.

The package is typically used when you have a Click CLI tool and want to keep its documentation in sync with the code without manual maintenance. Instead of writing command reference docs by hand, you add a simple block to your Markdown that references the CLI module, and the extension generates the documentation automatically. It supports both simple flat commands and complex hierarchical command groups.

Use it for:

• Auto-generate a CLI reference page for a Click application by pointing mkdocs-click at the root command group
• Embed command documentation within a larger MkDocs site without duplicating help text
• Maintain up-to-date command reference docs that stay synchronized with code changes automatically
• Document nested subcommands with customizable header levels to fit your documentation structure
• Display command options in either plain or table format depending on your documentation style

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates API documentation for Click command-line applications and embeds it into MkDocs sites as a Markdown extension.

Yes, if you use Click for CLI tools and MkDocs for documentation. Low install friction, permissive license, and no known vulnerabilities make it a safe choice. The aging maintenance status (494 days since last release) is a minor concern but not a blocker—the package is stable, the repository is not archived, and recent commits show ongoing activity. Install it when you want to eliminate manual CLI documentation maintenance.

Install

mkdocs-click on PyPI

pip install mkdocs-click

uv add mkdocs-click

poetry add mkdocs-click

Installing mkdocs-click

Before you install

Low install friction with only two runtime dependencies (click and markdown). Maintenance status is aging—last release was 494 days ago—but the repository remains active with recent commits and no archived status.

License in practice

Licensed under Apache-2.0 (permissive), allowing use in commercial and private projects with minimal restrictions.

Quickstart

pip install mkdocs-click

# In mkdocs.yml:
markdown_extensions:
    - mkdocs-click

# In your Markdown:
::: mkdocs-click
    :module: app.cli
    :command: cli

Requires a Click command object importable from a Python module; the module path must be resolvable at documentation build time.

Verify before relying

• Whether the package works with Click versions beyond those tested in CI
• Performance characteristics when documenting very large or deeply nested command hierarchies
• Compatibility with recent MkDocs versions and popular themes beyond ReadTheDocs

Package facts

Evidence: mkdocs_click-0.9.0-py3-none-any.whl

Keywords: click, mkdocs, mkdocs-plugin

Tags

More Documentation packages