Wondering what’s next for npm?Check out our public roadmap! »

    adr-log

    2.2.0 • Public • Published

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

    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

    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.

    Install

    npm i adr-log

    DownloadsWeekly Downloads

    4,196

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    21.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar
    • avatar