{"id":15107069,"url":"https://github.com/febus982/mkdocs-macros-adr-summary","last_synced_at":"2025-10-23T01:31:19.410Z","repository":{"id":218225014,"uuid":"745909036","full_name":"febus982/mkdocs-macros-adr-summary","owner":"febus982","description":"A plugin to generate a summary of a ADR directory","archived":false,"fork":false,"pushed_at":"2024-12-15T18:25:03.000Z","size":1711,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T16:43:44.539Z","etag":null,"topics":["adr","architecture-decision-records","madr","mkdocs","mkdocs-macros-plugin","mkdocs-plugin","mkdocs-plugins","nygard"],"latest_commit_sha":null,"homepage":"https://febus982.github.io/mkdocs-macros-adr-summary/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/febus982.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-20T14:16:54.000Z","updated_at":"2024-12-15T18:23:07.000Z","dependencies_parsed_at":"2024-04-26T12:47:26.470Z","dependency_job_id":"f0915ab9-ca26-42b6-bb5f-d6f16a645e5d","html_url":"https://github.com/febus982/mkdocs-macros-adr-summary","commit_stats":null,"previous_names":["febus982/mkdocs-macros-adr-summary"],"tags_count":3,"template":false,"template_full_name":"febus982/bootstrap-python-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/febus982%2Fmkdocs-macros-adr-summary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/febus982%2Fmkdocs-macros-adr-summary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/febus982%2Fmkdocs-macros-adr-summary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/febus982%2Fmkdocs-macros-adr-summary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/febus982","download_url":"https://codeload.github.com/febus982/mkdocs-macros-adr-summary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237763855,"owners_count":19362310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architecture-decision-records","madr","mkdocs","mkdocs-macros-plugin","mkdocs-plugin","mkdocs-plugins","nygard"],"created_at":"2024-09-25T21:04:12.121Z","updated_at":"2025-10-23T01:31:19.399Z","avatar_url":"https://github.com/febus982.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-macros-adr-summary\n![Static Badge](https://img.shields.io/badge/Python-3.9_%7C_3.10_%7C_3.11_%7C_3.12_%7C_3.13-blue?logo=python\u0026logoColor=white)\n[![Stable Version](https://img.shields.io/pypi/v/mkdocs-macros-adr-summary?color=blue)](https://pypi.org/project/mkdocs-macros-adr-summary/)\n[![stability-beta](https://img.shields.io/badge/stability-beta-33bbff.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)\n\n[![Python tests](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml/badge.svg?branch=main)](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)\n[![Maintainability](https://qlty.sh/badges/48b1b6a4-94d2-48d4-aced-3c93c183c9c3/maintainability.svg)](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)\n[![Code Coverage](https://qlty.sh/badges/48b1b6a4-94d2-48d4-aced-3c93c183c9c3/test_coverage.svg)](https://qlty.sh/gh/febus982/projects/mkdocs-macros-adr-summary)\n\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)\n[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](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 | ✅︎     | ✅︎    | ✅︎    | ✅︎    |\n| title     | ✅︎     | ✅︎    | ✅︎    | ✅︎    |\n| date      | ✅︎     | ✅︎    | ✅︎    | ✅︎    |\n| status    | ⚠      | ✅︎    | ✅︎    | ✅︎    |\n| statuses  | ✅︎     | ⚠     | ⚠     | ⚠     |\n| deciders  | ❌      | ✅︎    | ✅︎    | ✅︎    |\n| consulted | ❌      | ✅︎    | ✅︎    | ❌     |\n| informed  | ❌      | ✅︎    | ✅︎    | ❌     |\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffebus982%2Fmkdocs-macros-adr-summary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffebus982%2Fmkdocs-macros-adr-summary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffebus982%2Fmkdocs-macros-adr-summary/lists"}