View on GitHub

adr-log

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

Install with npm:

$ npm install -g adr-log

CLI

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

Usage

Examples

Printing the adr log to stdout

Consider a directory consisting of three files (0000-example-1.md, 0001-example-2.md, 0002-example-3.md). 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.

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

$ adr-log -i

Result in following index.md:

<!-- 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 -->

Developing

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

  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.

License

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

Released under the MIT License.