MkDocs-Click

0.9.0 · active · verified Sat Apr 11

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.

Warnings

breaking Support 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.
breaking Due 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.
gotcha The 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.
gotcha In 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.

Install

pip install mkdocs-click Install latest version

Imports

ClickExtension
```
from mkdocs_click.extension import ClickExtension
```
While this is the main extension class, typical usage of mkdocs-click is via MkDocs configuration (`mkdocs.yml`) rather than direct Python import in user applications.

Quickstart

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

view raw JSON →