docs/index.md
# 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://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability)
[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage)
[](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.
```
{% raw %}
{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}
{% endraw %}
```
`adr_style` can be `nygard` or `MADR3`
## 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.
```
{% raw %}
{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }}
{% endraw %}
```
The default template is:
```
{% raw %}
| 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 %}
{% endraw %}
```
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 | 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** and **MADR3**
* 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.
## 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 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 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