https://github.com/cmsirbu/mkdocs-ansible-collection
MkDocs Plugin that automatically generates pages for Ansible Collections.
https://github.com/cmsirbu/mkdocs-ansible-collection
ansible ansible-collection mkdocs mkdocs-plugin
Last synced: 4 months ago
JSON representation
MkDocs Plugin that automatically generates pages for Ansible Collections.
- Host: GitHub
- URL: https://github.com/cmsirbu/mkdocs-ansible-collection
- Owner: cmsirbu
- License: mit
- Created: 2024-07-27T21:40:25.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-01T13:57:46.000Z (8 months ago)
- Last Synced: 2025-09-20T04:00:44.492Z (5 months ago)
- Topics: ansible, ansible-collection, mkdocs, mkdocs-plugin
- Language: Python
- Homepage: https://mkdocs-ansible-collection.readthedocs.io/en/stable/
- Size: 165 KB
- Stars: 5
- Watchers: 1
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MkDocs Ansible Collection
[MkDocs](https://www.mkdocs.org) Plugin that automatically generates documentation pages for Ansible Collections. Check out the showcase over on the project's [documentation page](https://mkdocs-ansible-collection.readthedocs.io/en/stable/showcase/) and more detailed [User](https://mkdocs-ansible-collection.readthedocs.io/en/stable/user/) and [Developer](https://mkdocs-ansible-collection.readthedocs.io/en/stable/dev/) guides!
## Quick Start
1. Add the `mkdocs-ansible-collection` Python package to your project's docs dependencies. It will also install `ansible-core` to manage collections and get the required metadata.
```
pip install mkdocs-ansible-collection
```
2. Install any needed collection(s) using `ansible-galaxy collection install example.collection` or point ansible at the correct collection path.
3. Enable the plugin in your project's `mkdocs.yaml` file:
```yaml
plugins:
- "ansible-collection":
collections:
- fqcn: "example.collection"
```
4. Add an anchor page to the `nav` section of your project's `mkdocs.yaml` file:
```yaml
nav:
# The anchor is named after the Collection FQCN and it tells mkdocs where
# to generate the documentation tree. The following examples show all of
# the currently supported combinations:
- "Example Collection": "example.collection" # With an explicit page name
- "Nested Under Another Page":
- "example.collection" # Without a custom page name
```
For more details, check out the [User Guide](https://mkdocs-ansible-collection.readthedocs.io/en/stable/user/) and look at the live example of [this project's docs](https://github.com/cmsirbu/mkdocs-ansible-collection), which showcase how to build and host collection docs on the awesome [Read the Docs](https://about.readthedocs.com/) service!
## Contributions
Contributions of all sorts (bug reports, features, documentation etc.) are welcome! Any larger change, please open a new [issue](https://github.com/cmsirbu/mkdocs-ansible-collection/issues) to discuss it first.