Install adr-viewer with Homebrew

Project links

• Homepage

Commands and aliases

• adr-viewer

Project history

The project records its own first ADR on 2018-09-02, choosing to document its architecture decisions with ADRs and explicitly pointing users toward Nat Pryce's ADR Tools. Its README says it can show ADRs as a local web server or static content and can include Mermaid diagrams embedded in fenced code blocks.

The README documents a small CLI surface: `--adr-path`, `--output`, `--title`, `--serve`, `--port`, and `--help`. It defaults to `doc/adr/` because that is the default path generated by ADR Tools, showing that it was designed around the de facto file layout rather than inventing a new ADR store.

After a quiet period, the 1.4.0 RC release note said the maintainer had time to maintain the project properly again. The 1.4.0 production release gathered maintenance work including dependency/security updates, Python version testing, Homebrew installation documentation, UTF-8 output, parsing refactors, and Mermaid support; 1.5.0 RC1 later fixed Mermaid feature detection.

Adoption history

The tool is officially installable from PyPI and Homebrew according to its README, and the provided package facts show a Homebrew formula. That gives it a lower-friction adoption path for teams already using ADR Tools or plain Markdown ADR directories.

Its adoption is tied to the broader ADR convention rather than to a server product. Because it generates static content or runs a local server, it fits teams that want to publish architecture decisions inside existing documentation sites, CI artifacts, or repository pages.

How it is used

Users point `adr-viewer` at an ADR directory, usually `doc/adr/`, and either write an `index.html` file or serve the generated view on localhost. It can set a project title, change the output file, choose a port, and render Mermaid diagrams embedded in ADRs.

The project is useful when ADRs have grown beyond a handful of Markdown files. It provides navigation and visual treatment while preserving the simple repository storage model that made ADRs attractive in the first place.

Why package nerds care

adr-viewer is a neat packaging companion because it turns a documentation convention into a single CLI with no hosted service requirement. Homebrew packaging is particularly natural: install the command, run it against a repo, produce static HTML.

It also demonstrates how conventions propagate through packages. The default `doc/adr/` path is not a platform rule; it is inherited from ADR Tools and then reinforced by downstream tooling.

Timeline

• 2018: Project ADR 1 recorded the use of Architecture Decision Records.
• 2018: The project adopted ADR Tools' ADR convention and `doc/adr` layout.
• 2024: Version 1.4.0 RC1 announced renewed maintenance after a hiatus.
• 2024: Version 1.4.0 production release included dependency, testing, Homebrew, and Mermaid-related work.
• 2024: Version 1.5.0 RC1 fixed Mermaid feature detection.

Related projects

• ADR Tools is the upstream convention-setter for the default ADR path.
• Mermaid is supported for diagrams embedded inside ADR Markdown.

Sources

• https://github.com/mrwilson/adr-viewer#readme
• https://github.com/mrwilson/adr-viewer/releases
• https://github.com/mrwilson/adr-viewer/tree/master/doc/adr
• https://raw.githubusercontent.com/mrwilson/adr-viewer/master/doc/adr/0001-record-architecture-decisions.md
• source_facts.package-manager