mkdocs-macros-adr-summary 1.3.0

A plugin to generate a summary of a ADR directory

mkdocs-macros-adr-summary

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

The single ADR documents file names have to respect this format: 0000-my-decision-title.md

• start with 4 digits followed by the character -
• the rest of the file name can contain only letters, numbers, dashes and underscores ([A-Za-z0-9_-] regex)
• end with the .md extension

Examples and documentation can be found here

The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version, as soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced and will be documented in the GitHub release description.

Quick start

Enable the plugin in mkdocs.yml

plugins:
  - macros:
      modules:
        - 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.

{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}

adr_style can be nygard, MADR2, MADR3, or MADR4

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.

{{ adr_summary(adr_path="docs/adr", adr_style="MADR3",m) }}

The default template is:

| ID | Date | Decision | Status |
|----|------|----------|--------|
{% for d in documents %}| {{ d.document_id }} | {{ d.date.strftime('%d-%m-%Y') if d.date else "-"}} | [{{ d.title }}]({{ d.file_path }}) | {{ d.status }}  |
{% endfor %}

The documents variable in the jinja template is a Sequence of ADRDocument models:

@dataclass
class ADRDocument:
    file_path: str
    document_id: Optional[int] = None
    title: Optional[str] = None
    date: Optional[date] = None
    status: Optional[str] = None
    statuses: Sequence[str] = tuple()
    deciders: Optional[str] = None
    consulted: Optional[str] = None
    informed: Optional[str] = None

There are some differences in what metadata is available when using different formats:

	Nygard	MADR4	MADR3	MADR2
file_path	✅︎	✅︎	✅︎	✅︎
title	✅︎	✅︎	✅︎	✅︎
date	✅︎	✅︎	✅︎	✅︎
status	⚠	✅︎	✅︎	✅︎
statuses	✅︎	⚠	⚠	⚠
deciders	❌	✅︎	✅︎	✅︎
consulted	❌	✅︎	✅︎	❌
informed	❌	✅︎	✅︎	❌

• Nygard format
  • status is the last item statuses. (I don't believe we should use multiple statuses, however adr-tools allows it)
  • deciders, consulted and informed are not supported by the format
• MADR2, MADR3, and MADR4
  • I wasn't able to find an automated tool supporting superseding documents. By looking at the template it looks like there's a single status. statuses will return a list with a single status.
  • MADR4 uses decision-makers instead of deciders in the YAML frontmatter, but the parser maps it to the deciders field in the document model

Supported ADR formats

The supported ADR formats are:

• nygard format, it is recommended to use adr-tools to manage the directory
• MADR version 4
• MADR version 3
• MADR version 2

Commands for development

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

• make dev-dependencies: Install 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