# mkdocs-macros-adr-summary
[](https://pypi.org/project/mkdocs-macros-adr-summary/)
[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)
[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)
[](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)
[](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)
[](https://mypy-lang.org/)
[](https://github.com/psf/black)
[](https://github.com/charliermarsh/ruff)
[](https://github.com/PyCQA/bandit)
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](https://febus982.github.io/mkdocs-macros-adr-summary)
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`
```yaml
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.
```markdown
{{ 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.
```markdown
{{ adr_summary(adr_path="docs/adr", adr_style="MADR3",m) }}
```
The default template is:
```markdown
| 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:
```python
@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](https://github.com/npryce/adr-tools) to manage the directory
* `MADR` [version 4](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md)
* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)
## 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
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-macros-adr-summary",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "adr, architecture-decision-records, mkdocs, mkdocs-macro, mkdocs-macro-plugin, mkdocs-plugin, nygard",
"author": null,
"author_email": "Federico Busetti <729029+febus982@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/8a/f7/071ff9951484e155ccdd34adaefd58bfb566f6529f7651a38afa9726dccf/mkdocs_macros_adr_summary-1.2.0.tar.gz",
"platform": null,
"description": "# mkdocs-macros-adr-summary\n\n[](https://pypi.org/project/mkdocs-macros-adr-summary/)\n[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)\n\n[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)\n[](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)\n[](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)\n\n[](https://mypy-lang.org/)\n[](https://github.com/psf/black)\n[](https://github.com/charliermarsh/ruff)\n[](https://github.com/PyCQA/bandit)\n\nThis is a macro plugin to generates summaries from a list of a ADR documents in a directory.\n\nThe single ADR documents file names have to respect this format: `0000-my-decision-title.md`\n\n* start with 4 digits followed by the character `-`\n* the rest of the file name can contain only letters, numbers, dashes and underscores (`[A-Za-z0-9_-]` regex)\n* end with the `.md` extension\n\nExamples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)\n\nThe package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,\nas soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced\nand will be documented in the GitHub release description.\n\n## Quick start\n\nEnable the plugin in `mkdocs.yml`\n\n```yaml\nplugins:\n - macros:\n modules:\n - mkdocs_macros_adr_summary\n```\n\nCreate a markdown page in your mkdocs website and use the `adr_summary` macro providing\nthe path containing your ADR files relative to the `mkdocs.yml` file.\n\n```markdown\n{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"nygard\") }}\n```\n\n`adr_style` can be `nygard`, `MADR2`, `MADR3`, or `MADR4`\n\n## More customization\n\nThe page output is generated using a jinja template, but you can provide a custom one. The file path\nmust still be relative to the `mkdocs.yml` file.\n\n```markdown\n{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"MADR3\",m) }}\n```\n\nThe default template is:\n\n```markdown\n| ID | Date | Decision | Status |\n|----|------|----------|--------|\n{% for d in documents %}| {{ d.document_id }} | {{ d.date.strftime('%d-%m-%Y') if d.date else \"-\"}} | [{{ d.title }}]({{ d.file_path }}) | {{ d.status }} |\n{% endfor %}\n```\n\nThe `documents` variable in the jinja template is a Sequence of `ADRDocument` models:\n\n```python\n@dataclass\nclass ADRDocument:\n file_path: str\n document_id: Optional[int] = None\n title: Optional[str] = None\n date: Optional[date] = None\n status: Optional[str] = None\n statuses: Sequence[str] = tuple()\n deciders: Optional[str] = None\n consulted: Optional[str] = None\n informed: Optional[str] = None\n```\n\nThere are some differences in what metadata is available when using different formats:\n\n| | Nygard | MADR4 | MADR3 | MADR2 |\n|-----------|--------|-------|-------|-------|\n| file_path | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| title | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| date | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| status | \u26a0 | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| statuses | \u2705\ufe0e | \u26a0 | \u26a0 | \u26a0 |\n| deciders | \u274c | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| consulted | \u274c | \u2705\ufe0e | \u2705\ufe0e | \u274c |\n| informed | \u274c | \u2705\ufe0e | \u2705\ufe0e | \u274c |\n\n* **Nygard format**\n * `status` is the last item `statuses`. (I don't believe we should use multiple\n statuses, however `adr-tools` allows it)\n * `deciders`, `consulted` and `informed` are not supported by the format\n* **MADR2**, **MADR3**, and **MADR4**\n * I wasn't able to find an automated tool supporting superseding documents.\n By looking at the template it looks like there's a single status.\n `statuses` will return a list with a single status.\n * MADR4 uses `decision-makers` instead of `deciders` in the YAML frontmatter, but the parser maps it to the `deciders` field in the document model\n\n## Supported ADR formats\n\nThe supported ADR formats are:\n* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory\n* `MADR` [version 4](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md)\n* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)\n* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)\n\n## Commands for development\n\nAll the common commands used during development can be run using make targets:\n\n* `make dev-dependencies`: Install dev requirements\n* `make test`: Run test suite\n* `make check`: Run tests, code style and lint checks\n* `make fix`: Run code style and lint automatic fixes (where possible)\n* `make docs`: Render the mkdocs website locally\n",
"bugtrack_url": null,
"license": null,
"summary": "A plugin to generate a summary of a ADR directory",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://febus982.github.io/mkdocs-macros-adr-summary",
"Repository": "https://github.com/febus982/mkdocs-macros-adr-summary"
},
"split_keywords": [
"adr",
" architecture-decision-records",
" mkdocs",
" mkdocs-macro",
" mkdocs-macro-plugin",
" mkdocs-plugin",
" nygard"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bebd3a8081452eb6d2f92f5d3e25fe0b2235652345019c6029552903d77d1a53",
"md5": "d2f91b7b6f48ece184749a89cbf813cf",
"sha256": "1863e3d2598d691100269c57bc616ad7476d8e035e30a8f91d218908ffab7ab7"
},
"downloads": -1,
"filename": "mkdocs_macros_adr_summary-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2f91b7b6f48ece184749a89cbf813cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 21696,
"upload_time": "2025-10-10T19:54:00",
"upload_time_iso_8601": "2025-10-10T19:54:00.387375Z",
"url": "https://files.pythonhosted.org/packages/be/bd/3a8081452eb6d2f92f5d3e25fe0b2235652345019c6029552903d77d1a53/mkdocs_macros_adr_summary-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8af7071ff9951484e155ccdd34adaefd58bfb566f6529f7651a38afa9726dccf",
"md5": "47c77eb0cbd24e5f25f8e01a8fabef8b",
"sha256": "e147431bd910dd7df30efc44477bdb14bf405ba09be4b011a69f4de4dec6b93b"
},
"downloads": -1,
"filename": "mkdocs_macros_adr_summary-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "47c77eb0cbd24e5f25f8e01a8fabef8b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 10914,
"upload_time": "2025-10-10T19:54:01",
"upload_time_iso_8601": "2025-10-10T19:54:01.506954Z",
"url": "https://files.pythonhosted.org/packages/8a/f7/071ff9951484e155ccdd34adaefd58bfb566f6529f7651a38afa9726dccf/mkdocs_macros_adr_summary-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 19:54:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "febus982",
"github_project": "mkdocs-macros-adr-summary",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mkdocs-macros-adr-summary"
}
JSON
