Skip to content

User Guide

This MkDocs plugin generates documentation pages dynamically from Ansible Collection metadata.

Requirements and Compatibility

The dependencies and minimum supported versions are as follows:

While the Material for MkDocs theme is not a direct requirement, the plugin has only been developed and tested with it.

Getting Started

Add the mkdocs-ansible-collection Python package to your project's docs dependencies using your project management tool of choice. It will also install ansible-core to manage collections and get the required metadata.

pip install mkdocs-ansible-collection

Install any needed collection(s) using ansible-galaxy collection install example.collection or ansible-galaxy collection install -r requirements.yaml or point ansible at the correct collection path via ansible.cfg.

Each Ansible Collection FQCN must be added to the Plugin Configuration and have an anchor defined in the nav section of your docs! See both sections below for details.

Plugin Configuration

Add the plugin to your project's mkdocs.yaml file and list all the Ansible Collections that you want documentation generated for:

plugins:
  - "ansible-collection":
      collections:
        - fqcn: "ansible.builtin"
        - fqcn: "arista.eos"
        - fqcn: "networktocode.nautobot"
        - fqcn: "ansible.netcommon"

Anchor Pages

Add one anchor to the nav section of your project's mkdocs.yaml file for each collection defined in the plugin configuration. The anchor is named after the Collection FQCN and it tells mkdocs where to generate the documentation tree.

There are several combinations for how the resulting page is named and displayed in the documentation navigation:

  • The anchor can be as simple as just the collection name, for example "arista.eos" and the page name will default to exactly this collection name.
  • The page name can also be customized to anything you'd like, for example "My Cool Collection": "example.collection".
  • The anchor can be nested, with or without the custom page name, under any section or page in your documentation tree.
nav:
  - "Collection Showcase":
    - "showcase/index.md"
    - "ansible.posix"
    - "ansible.netcommon"
    - "ansible.utils"
    - "Arista EOS": "arista.eos"
  - "Ansible Builtins": "ansible.builtin"
  - "networktocode.nautobot"

Live Example

This project's documentation site serves as a live example on how to set up documentation for a project using this plugin! Feel free to use it as a template which also includes the necessary configuration to build and host the documentation on the awesome Read the Docs service!

Ansible Plugin Support

Plugin Type Support
become ✅
cache ✅
callback ✅
connection ✅
filter ✅
inventory ✅
keyword ❌
lookup ✅
module ✅
shell ✅
strategy ✅
test ✅
vars ✅
cliconf ✅
httpapi ✅
netconf ✅
role ❌