{"id":17750506,"url":"https://github.com/syn54x/mkdocs-typer2","last_synced_at":"2026-01-16T14:46:30.767Z","repository":{"id":259539137,"uuid":"878209397","full_name":"syn54x/mkdocs-typer2","owner":"syn54x","description":"Mkdocs Plugin For Typer CLI Docs","archived":false,"fork":false,"pushed_at":"2026-01-14T04:10:59.000Z","size":754,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-14T07:24:47.864Z","etag":null,"topics":["mkdocs","plugin","typer","typer-cli"],"latest_commit_sha":null,"homepage":"https://syn54x.github.io/mkdocs-typer2/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syn54x.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"thanks_dev":"u/gh/ox54","custom":["https://www.paypal.com/donate/?hosted_button_id=UPXWQEA2G3J3L"]}},"created_at":"2024-10-25T00:54:15.000Z","updated_at":"2026-01-14T04:10:24.000Z","dependencies_parsed_at":"2024-10-26T10:29:39.181Z","dependency_job_id":"8c390a5f-cc34-4f90-ae90-6e2c8dafe802","html_url":"https://github.com/syn54x/mkdocs-typer2","commit_stats":null,"previous_names":["syn54x/mkdocs-typer2"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/syn54x/mkdocs-typer2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syn54x%2Fmkdocs-typer2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syn54x%2Fmkdocs-typer2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syn54x%2Fmkdocs-typer2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syn54x%2Fmkdocs-typer2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syn54x","download_url":"https://codeload.github.com/syn54x/mkdocs-typer2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syn54x%2Fmkdocs-typer2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs","plugin","typer","typer-cli"],"created_at":"2024-10-26T12:05:10.525Z","updated_at":"2026-01-16T14:46:30.755Z","avatar_url":"https://github.com/syn54x.png","language":"Python","readme":"# mkdocs-typer2\n\n[![PyTest](https://img.shields.io/badge/Pytest-0A9EDC?style=for-the-badge\u0026logo=pytest\u0026logoColor=white)](https://docs.pytest.org/)\n[![Ruff](https://img.shields.io/badge/Ruff-FFC107?style=for-the-badge\u0026logo=python\u0026logoColor=black)](https://docs.astral.sh/ruff/)\n[![MkDocs](https://img.shields.io/badge/MkDocs-000000?style=for-the-badge\u0026logo=markdown\u0026logoColor=white)](https://www.mkdocs.org/)\n[![Typer](https://img.shields.io/badge/Typer-FF4B4B?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://typer.tiangolo.com/)\n[![UV](https://img.shields.io/badge/UV-2C2C2C?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://github.com/astral-sh/uv)\n[![Python](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12|%203.13%20|%203.14-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![PyPI](https://img.shields.io/pypi/v/mkdocs-typer2?style=for-the-badge)](https://pypi.org/project/mkdocs-typer2/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-D22128?style=for-the-badge\u0026logo=apache\u0026logoColor=white)](https://opensource.org/licenses/Apache-2.0)\n[![Downloads](https://img.shields.io/pepy/dt/mkdocs-typer2?style=for-the-badge)](https://pepy.tech/project/mkdocs-typer2)\n[![Codecov](https://img.shields.io/codecov/c/github/syn54x/mkdocs-typer2?style=for-the-badge\u0026logo=codecov\u0026logoColor=white)](https://codecov.io/gh/syn54x/mkdocs-typer2)\n[![Issues](https://img.shields.io/github/issues/syn54x/mkdocs-typer2?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/syn54x/mkdocs-typer2/issues)\n\nA MkDocs plugin that automatically generates beautiful documentation for your Typer CLI applications.\n\nYou might be wondering why there are two plugins for Typer. The [`mkdocs-typer`](https://github.com/bruce-szalwinski/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 \u003cmodule\u003e utils docs` command. This plugin simply leverages that system to generate the documentation for your Typer CLIs.\n\nI 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!\n\n- [Read The Docs](https://syn54x.github.io/mkdocs-typer2/)\n- [Check out a demo](https://syn54x.github.io/mkdocs-typer2/cli)\n\n## Features\n\n- Seamlessly integrates with MkDocs and Material theme\n- Automatically generates CLI documentation from your Typer commands\n- Supports all Typer command features including arguments, options, and help text\n- Easy to configure and use\n- `pretty` feature for formatting arguments \u0026 options as tables\n- `engine` option to select legacy markdown parsing or native Click walking\n- Global plugin configuration or per-documentation block configuration\n\n## How It Works\n\nThe 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.\n\nThe plugin works by:\n\n1. Registering a Markdown extension that processes special directive blocks\n2. Resolving the command tree (legacy: `typer \u003cmodule\u003e utils docs`, native: Click walk)\n3. Formatting arguments and options as lists or tables based on `pretty`\n4. Integrating the resulting HTML into your MkDocs site\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install mkdocs-typer2\n```\n\nInstall using uv:\n\n```bash\nuv add mkdocs-typer2\n```\n\n### Requirements\n\n- Python 3.10 or higher\n- MkDocs 1.6.1 or higher\n- Typer 0.12.5 or higher\n- Pydantic 2.9.2 or higher\n\n## Configuration\n\n### Basic Configuration\n\nAdd the plugin to your `mkdocs.yml` file:\n\n```yaml\nplugins:\n  - mkdocs-typer2\n```\n\n### Pretty Mode\n\nThe plugin offers a `pretty` option that can be set in your `mkdocs.yml` file to enable table-based formatting for options and arguments:\n\n```yaml\nplugins:\n  - mkdocs-typer2:\n      pretty: true\n```\n\n**Options when `:pretty: false`:**\n\n\n**Options**:\n* `--name`: The name of the project  [required]\n\n**Options when `:pretty: true`:**\n\n| Name | Description | Required | Default |\n| --- | --- | --- | --- |\n| `--name` | The name of the project | Yes | - |\n\n\n### Engine Selection\n\nUse `engine` to select how the command tree is built:\n\n```yaml\nplugins:\n  - mkdocs-typer2:\n      engine: native  # or legacy\n```\n\n## Usage\n\n### Basic Usage\n\nIn your Markdown files, use the `::: mkdocs-typer2` directive to generate documentation for your Typer CLI:\n\n```markdown\n::: mkdocs-typer2\n    :module: my_module\n    :name: mycli\n```\n\n### Required Parameters\n\n- `: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`.\n\n### Optional Parameters\n\n- `:name:` - The name of the CLI. If left blank, your CLI will simply be named `CLI` in your documentation.\n- `:pretty:` - Set to `true` to enable pretty formatting for this specific documentation block, overriding the global setting.\n- `:engine:` - `legacy` parses Typer markdown (deprecated). `native` walks Click and renders lists or tables based on `pretty`.\n\n## Advanced Usage\n\n### Per-Block Pretty Configuration\n\nYou can override the global pretty setting for individual documentation blocks:\n\n```markdown\n::: mkdocs-typer2\n    :module: my_module.cli\n    :name: mycli\n    :pretty: true\n    :engine: native\n```\n\n### Multiple CLI Documentation\n\nYou can document multiple CLIs in the same MkDocs site by using multiple directive blocks:\n\n```markdown\n# Main CLI\n\n::: mkdocs-typer2\n    :module: my_module.cli\n    :name: mycli\n\n# Admin CLI\n\n::: mkdocs-typer2\n    :module: my_module.admin\n    :name: admin-cli\n```\n\n## Example\n\nThis repository is a good example of how to use the plugin. We have a simple CLI located in `src/mkdocs_typer2/cli/cli.py`.\n\nThe CLI's documentation is automatically generated using the block level directive in `docs/cli.md`:\n\n```markdown\n::: mkdocs-typer2\n    :module: mkdocs_typer2.cli.cli\n    :name: mkdocs-typer2\n    :engine: legacy\n```\n\nAnd the pretty versions in `docs/cli-pretty-legacy.md` and `docs/cli-pretty-native.md`:\n\n```markdown\n::: mkdocs-typer2\n    :module: mkdocs_typer2.cli.cli\n    :name: mkdocs-typer2\n    :pretty: true\n    :engine: legacy\n```\n\n```markdown\n:::: mkdocs-typer2\n    :module: mkdocs_typer2.cli.cli\n    :name: mkdocs-typer2\n    :pretty: true\n    :engine: native\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.\n","funding_links":["https://thanks.dev/u/gh/ox54","https://www.paypal.com/donate/?hosted_button_id=UPXWQEA2G3J3L"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyn54x%2Fmkdocs-typer2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyn54x%2Fmkdocs-typer2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyn54x%2Fmkdocs-typer2/lists"}