{"id":4114,"library":"mkdocs-click","title":"MkDocs-Click","description":"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.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/mkdocs/mkdocs-click","tags":["mkdocs","click","documentation","cli","extension"],"install":[{"cmd":"pip install mkdocs-click","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is an MkDocs extension and requires MkDocs to function. mkdocs-click pins MkDocs to `>=1.2,<2.0`.","package":"mkdocs","optional":false},{"reason":"This library generates documentation for Click applications and relies heavily on Click's introspection capabilities. mkdocs-click pins Click to `>=7,<9`.","package":"click","optional":false}],"imports":[{"note":"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.","symbol":"ClickExtension","correct":"from mkdocs_click.extension import ClickExtension"}],"quickstart":{"code":"mkdocs new my-click-docs\ncd my-click-docs\npip install mkdocs mkdocs-click click\n\n# --- my_cli.py ---\nimport click\n\n@click.group()\ndef cli():\n    \"\"\"My super CLI tool.\"\"\"\n    pass\n\n@cli.command()\n@click.option('--count', default=1, help='Number of greetings.')\n@click.argument('name')\ndef hello(count, name):\n    \"\"\"Greets the NAME for a COUNT times.\"\"\"\n    for x in range(count):\n        click.echo(f\"Hello {name}!\")\n\n# --- mkdocs.yml ---\nsite_name: My Click Documentation\n\nextensions:\n  - mkdocs-click\n\n# --- docs/index.md ---\n# My Click Application Documentation\n\n```python\n# my_cli.py\nimport click\n\n@click.group()\ndef cli():\n    \"\"\"My super CLI tool.\"\"\"\n    pass\n\n@cli.command()\n@click.option('--count', default=1, help='Number of greetings.')\n@click.argument('name')\ndef hello(count, name):\n    \"\"\"Greets the NAME for a COUNT times.\"\"\"\n    for x in range(count):\n        click.echo(f\"Hello {name}!\")\n```\n\n:::{.mkdocs-click}\n#:\n  :module: my_cli\n  :command: cli\n:::\n\n# Building and serving\nmkdocs build\nmkdocs serve\n","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.9 or higher.","message":"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.","severity":"breaking","affected_versions":">=0.9.0"},{"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.","message":"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`).","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Upgrade to version 0.8.1 or newer. If using an older version, ensure there is an explicit newline after the `:::` block.","message":"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.","severity":"gotcha","affected_versions":"<0.8.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}