Generate an architectural decision log out of architectural decision records (ADRs).
Table of Contents
- Related Tooling
Install with npm:
npm install -g adr-log
Usage: adr-log [-d <directory>] [-i] <input>input: The markdown file to contain the table of contents.If no <input> file is specified, an index.md file containing the log is created in the current directory.-i: Edit the <input> file directly, injecting the log at <!-- adrlog -->.Using only the -i flag, the tool will scan the current working directory for all *.md files andinject the resulting adr-log into the default index.md file.(Without this flag, the default is to print the log to stdout.)-d: Scans the given <directory> for .md files.(Without this flag, the current working directory is chosen as default.)-h: Shows how to use this program
Printing the adr log to stdout
Consider a directory consisting of three files (
Execute following command:
adr-log -d .
This outputs following log on your console:
* - Example 1* - Example 2* - Example 3
Generating an index.md file containing the adr log
Since this is basically a fork of Jon Schlinkert's markdown-toc, you can also choose to insert the log into an existing file.
For this to work the file must contain an opening
<!-- adrlog --> code comment, after which the log will be inserted.
If the file already contains an adrlog surrounded by an opening
<!-- adrlog --> and closing
<!-- adrlogstop --> code comment, the existing is be replaced.
-i alone (
adr-log -i) generates an
index.md file in the current working directory containing the log.
$ adr-log -i
Result in following
<!-- adrlog -->* - Example 1* - Example 2* - Example 3<!-- adrlogstop -->
- search recursively underneath the given directory
- allow date prefixes as well as number prefixes
- allow specification of
dateproperties in frontmatter
- fallback to auto-numbering for ADRs without filename prefixes or frontmatter
node cli.jsto execute the CLI. Also works with relative directgories. E.g.,
node ../../../adr-log/cli.js -d .runs adr-log and outputs the result to the console.
- You can turn on debugging output by adjusting lines 6 and 7 in
- Use relase-it and github-release-from-changelog for release management. See also ADR-0003.
adr-tools is the most prominent related tool.
It supports generating an ADR log by using
adr generate toc.
An example to can be investigated at https://github.com/npryce/adr-tools/blob/master/tests/generate-contents.expected.
The difference to adr-tools is
- adr-log is available using
npmand thus more easy to install.
- adr-tools does not include the heading of each ADR into the output.
Released under the MIT License.