View on GitHub


Generate an architectural decision record log (adr-log) out of architectural decision records (ADRs)

adr-log NPM version

Generate an architectural decision log out of architectural decision records (ADRs).

Table of Contents


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 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 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]( - Example 1
- [ADR-0001]( - Example 2
- [ADR-0002]( - Example 3

Generating an 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.

Using -i alone (adr-log -i) generates an file in the current working directory containing the log.

$ adr-log -i

Result in following

<!-- adrlog -->

- [ADR-0000]( - Example 1
- [ADR-0001]( - Example 2
- [ADR-0002]( - Example 3

<!-- adrlogstop -->


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

The difference to adr-log is

  1. adr-log is available using npm and thus more easy to install.
  2. adr-tools does not include the heading of each ADR into the output.


Copyright © 2017 Tino Stadelmaier, Oliver Kopp, Armin Hüneburg, Tobias Wältken.

Released under the MIT License.