mkdocs-click

library0.9.0pypypi✓ verified 23d ago

MkDocs-Click is an MkDocs extension designed to automatically generate comprehensive documentation for Click command-line applications. It parses Click command structures and renders them directly into MkDocs pages, including options, arguments, and subcommands. The current version is 0.9.0, and it maintains an active release cadence, adapting to changes in both MkDocs and Click.

devops web-framework

pip install mkdocs-click

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · MKDOCS-CLICK

mkdocs-click

devopspythonv0.9.0

Install

2.0s avg

Import

252ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.260s · 19.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.244s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MKClickExtension

✓ from mkdocs_click import MKClickExtension

✗ from mkdocs_click.extension import ClickExtension

makeExtension

✓ from mkdocs_click import makeExtension

MkDocsClickException

✓ from mkdocs_click import MkDocsClickException

To use mkdocs-click, first install it alongside MkDocs. Then, configure your `mkdocs.yml` to include the `mkdocs-click` extension. Create a Python file containing your Click application and reference it in your Markdown file using the `mkdocs-click` directive. The example shows a basic Click CLI and its integration into an MkDocs project.

mkdocs new my-click-docs cd my-click-docs pip install mkdocs mkdocs-click click # --- my_cli.py --- import click @click.group() def cli(): """My super CLI tool.""" pass @cli.command() @click.option('--count', default=1, help='Number of greetings.') @click.argument('name') def hello(count, name): """Greets the NAME for a COUNT times.""" for x in range(count): click.echo(f"Hello {name}!") # --- mkdocs.yml --- site_name: My Click Documentation extensions: - mkdocs-click # --- docs/index.md --- # My Click Application Documentation ```python # my_cli.py import click @click.group() def cli(): """My super CLI tool.""" pass @cli.command() @click.option('--count', default=1, help='Number of greetings.') @click.argument('name') def hello(count, name): """Greets the NAME for a COUNT times.""" for x in range(count): click.echo(f"Hello {name}!") ``` :::{.mkdocs-click} #: :module: my_cli :command: cli ::: # Building and serving mkdocs build mkdocs serve

mkdocs --version

Debug

Known issues

breakingSupport for Python 3.8 has been dropped in version 0.9.0. Users on Python 3.8 or older must upgrade their Python environment or use mkdocs-click version 0.8.x or earlier.

fix

Upgrade Python to 3.9 or higher.

affects: >=0.9.0

breakingDue to upstream breaking changes in Click, mkdocs-click versions may have specific compatibility ranges. Version 0.6.0 explicitly adjusted to a breaking change in Click. Ensure your Click version is compatible with your mkdocs-click version (currently Click `>=7,<9`).

fix

Refer to the mkdocs-click `install_requires` for the supported Click version range and ensure your project's Click dependency falls within this range.

affects: >=0.6.0

gotchaThe behavior of `--help` options changed in version 0.3.0. Previously, `--help` was automatically dropped from the generated documentation; it is now kept in options by default. This might change the rendered output for older configurations.

fix

Review generated documentation if you upgrade from versions prior to 0.3.0 to ensure the `--help` option display is as desired. Use the `:exclude:` option if you need to manually hide it.

affects: >=0.3.0

gotchaIn versions prior to 0.8.1, the `:::{.mkdocs-click}` directive required an extra newline at the end of the file or before subsequent content to be properly parsed. This could lead to content not being rendered.

fix

Upgrade to version 0.8.1 or newer. If using an older version, ensure there is an explicit newline after the `:::` block.

affects: <0.8.1

Upgrade

Version history

0.9.0latest on PyPI · released Apr 7, 2025

Audit

Dependencies

mkdocsrequiredThis is an MkDocs extension and requires MkDocs to function. mkdocs-click pins MkDocs to `>=1.2,<2.0`.

clickrequiredThis library generates documentation for Click applications and relies heavily on Click's introspection capabilities. mkdocs-click pins Click to `>=7,<9`.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/mkdocs/mkdocs-click ↗

packagehttps://pypi.org/project/mkdocs-click/ ↗

changeloghttps://github.com/mkdocs/mkdocs-click/blob/master/CHANGELOG.md ↗