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 and inject 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:
- [ADR-0000](0000-example-1.md) - Example 1 - [ADR-0001](0001-example-2.md) - Example 2 - [ADR-0002](0002-example-3.md) - 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 --> - [ADR-0000](0000-example-1.md) - Example 1 - [ADR-0001](0001-example-2.md) - Example 2 - [ADR-0002](0002-example-3.md) - Example 3 <!-- adrlogstop -->
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-log 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.