Adr-log NPM | npm.io

adr-log

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

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  code comment, after which the log will be inserted.

If the file already contains an adrlog surrounded by an opening  and closing  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 -->

Alternative Indexing

search recursively underneath the given directory
allow date prefixes as well as number prefixes
allow specification of index or date properties in frontmatter
fallback to auto-numbering for ADRs without filename prefixes or frontmatter

Developing

Run node cli.js to 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 cli.js.
Use relase-it and github-release-from-changelog for release management. See also ADR-0003.

Related Tooling

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