Repository navigation
Support links in YAML frontmatter #216
Description
I started using ADR and in particular MADR with YAML frontmatter for the metadata. One thing that is not clear to me is how to link to another ADR in the metadata, not just in the free form text.
For example, when superseding, how do I link to the ADR it is superseded by so that a tool could parse that and do something with it (e.g., render a link to the other ADR)?
I found a convenient tool called adrs which has links: https://joshrotenberg.com/adrs/templates.html#template-variables
So when superseding I get:
---
number: 1
status: superseded
links:
- target: 2
kind: supersededby
---
# title
...It does not seem it is part of the specification right now but it would be great to have the ability to specify links in such a way (or similar).
Activity
koppor commentedon Jun 21, 2026
Internal note: In v2, we had the link to the superseded link at the
statusLink. https://github.com/adr/madr/blob/release/v3/template/adr-template.md
We remvoed it (https://github.com/adr/madr/blob/develop/CHANGELOG.md#removed), but without written reasoning. As far as I recoll, parsing was hard.
Thus, your input shows how "clean" YAML could be used. I don't see any hyperlinks here, but I think, the intention of the links is kind of RDF-Triples allowing local ADRs as source and target only. It's still not clear to me how this will work with large projects (#10).
mschoettle commentedon Jul 27, 2026
Good point. Yes, I think that is the intention. Here is the documentation for linking: https://joshrotenberg.com/adrs/commands/link.html
If I understand the large projects use case correctly, the ADRs still live in each project. In that case, the viewer/renderer could derive the correct hyperlinks. If cross-project references need to be supported, then maybe allowing relative and absolute references would make this possible.
koppor commentedon Aug 28, 2026
Note, the link above is the
--ngmode of the tool.