mkdocstrings-github

A GitHub Actions handler for mkdocstrings.

For example, the following page is generated from actions/checkout:

You can install the GitHub handler by specifying it as a dependency:

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings-github",
]

after which the generated documentation can be inserted in the markdown page with:

::: <path-to-action-or-workflow>
    handler: github

Features

• 📝 Automatic Example Signature: Displays an example call signature alongside the description. The version shown can be the latest release, latest major, current reference, or any custom string.
• ✨ Enhanced Markdown Descriptions: All description elements are parsed using a markdown parser, enabling comprehensive formatting and rich documentation capabilities.
• 🧩 Individual Parameter Hyperlinks: Each action or workflow parameter—including inputs, outputs, and secrets—receives a unique HTML id, facilitating direct linking to specific parameter documentation.
• 🔒 Automated Permission Aggregation: For reusable workflows, if permissions are specified at the job level rather than the workflow level, the required final permissions are automatically determined and displayed in the signature.
• 🔗 Parameter cross-linking: Link to other parameters of the action or workflow via a simple Markdown syntax.
• 🧑‍🤝‍🧑 Parameter grouping: Organize related inputs, outputs, and secrets into visual groups using inline YAML comments for clearer documentation structure.