Skip to main content

A plugin to generate a summary of a ADR directory

Project description

mkdocs-macros-adr-summary

Static Badge Stable Version stability-beta

Python tests Bandit checks Maintainability Test Coverage

Checked with mypy Code style: black Ruff security: bandit

This is a macro plugin to generates summaries from a list of a ADR documents in a directory.

Examples and documentation can be found here

Quick start

Enable the plugin in mkdocs.yml

plugins:
  - macros:
        module_name: mkdocs_macros_adr_summary

Create a markdown page in your mkdocs website and use the adr_summary macro providing the path containing your ADR files relative to the mkdocs.yml file.

# Summary

{{ adr_summary(adr_path="docs/adr") }}

More customization

The page output is generated using a jinja template, but you can provide a custom one. The file path must still be relative to the mkdocs.yml file.

# Summary

{{ adr_summary(adr_path="docs/adr", template_file="other.jinja") }}

The default template is:

## Document list

{% for d in documents %}
* [{{ d.title }}]({{ d.filename }})
    * `{{ d.date.strftime('%d-%m-%Y') }}`
    * `{{ d.file_path }}`
    {% if d.statuses %}
    * Statuses:
        {% for status in d.statuses %}
        * {{ status }}
        {% endfor %}
    {% endif %}
{% endfor %}

The document variable in the jinja template is a Sequence of:

@dataclass
class ADRDocument:
    file_path: str
    title: str
    date: Optional[date]
    statuses: Optional[Sequence[str]]

Supported ADR formats

The only supported ADR format currently is the nygard format, it is recommended to use adr-tools to manage the directory.

Support for MADR versions 2 and 3 will be added with future iterations.

Commands for development

All the common commands used during development can be run using make targets:

  • make dev-dependencies: Install dev requirements
  • make update-dependencies: Update dev requirements
  • make test: Run test suite
  • make check: Run tests, code style and lint checks
  • make fix: Run code style and lint automatic fixes (where possible)
  • make docs: Render the mkdocs website locally

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_macros_adr_summary-0.0.1.tar.gz (5.8 kB view hashes)

Uploaded Source

Built Distribution

mkdocs_macros_adr_summary-0.0.1-py3-none-any.whl (7.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page