generate
Generate documentation from ADRs.
Usage
adrs generate <SUBCOMMAND>
Subcommands
| Subcommand | Description |
|---|---|
toc | Generate a table of contents |
graph | Generate a Graphviz dependency graph |
book | Generate an mdbook |
generate toc
Generate a markdown table of contents to stdout.
Usage
adrs generate toc [OPTIONS]
Options
| Option | Description |
|---|---|
-o, --ordered | Use ordered list (1. 2. 3.) instead of bullets |
-i, --intro <FILE> | Prepend content from file |
-O, --outro <FILE> | Append content from file |
-p, --prefix <PREFIX> | Prefix for ADR links |
--ng | Use NextGen mode |
-C, --cwd <DIR> | Working directory |
-h, --help | Print help |
Examples
Basic Table of Contents
adrs generate toc
Output:
* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Use PostgreSQL for persistence](0002-use-postgresql-for-persistence.md)
* [3. API versioning strategy](0003-api-versioning-strategy.md)
Ordered List
adrs generate toc --ordered
Output:
1. [1. Record architecture decisions](0001-record-architecture-decisions.md)
2. [2. Use PostgreSQL for persistence](0002-use-postgresql-for-persistence.md)
3. [3. API versioning strategy](0003-api-versioning-strategy.md)
Save to File
adrs generate toc > doc/adr/README.md
With Intro and Outro Files
adrs generate toc -i intro.md -O outro.md > doc/adr/README.md
Link Prefix for Wikis
adrs generate toc -p "wiki/adr/"
generate graph
Generate a Graphviz DOT graph showing ADR relationships.
Usage
adrs generate graph [OPTIONS]
Options
| Option | Description |
|---|---|
-p, --prefix <PREFIX> | Prefix for node URLs |
-e, --extension <EXT> | File extension for links (default: md) |
--ng | Use NextGen mode |
-C, --cwd <DIR> | Working directory |
-h, --help | Print help |
Examples
Basic Graph
adrs generate graph
Output:
digraph {
node [shape=plaintext];
_1 [label="1. Record architecture decisions"; URL="0001-record-architecture-decisions.md"];
_2 [label="2. Use PostgreSQL"; URL="0002-use-postgresql.md"];
_3 [label="3. Use MySQL instead"; URL="0003-use-mysql-instead.md"];
edge [style=dotted, weight=10];
_1 -> _2;
_2 -> _3;
edge [style=solid, weight=1];
_3 -> _2 [label="Supersedes"];
}
Save to File
adrs generate graph > doc/adr/graph.dot
Render as PNG
Using Graphviz:
adrs generate graph | dot -Tpng -o doc/adr/graph.png
Render as SVG
adrs generate graph | dot -Tsvg -o doc/adr/graph.svg
HTML Links with Custom Extension
adrs generate graph -e html -p "/docs/adr/"
Graph Features
- Each ADR is a node with its number and title
- Sequential ADRs are connected with dotted lines
- Explicit links between ADRs shown as solid edges with labels
- Nodes link to their ADR files (clickable in SVG)
generate book
Generate an mdbook from your ADRs.
Usage
adrs generate book [OPTIONS]
Options
| Option | Description |
|---|---|
-o, --output <DIR> | Output directory (default: book) |
-t, --title <TITLE> | Book title |
-d, --description <DESC> | Book description |
--ng | Use NextGen mode |
-C, --cwd <DIR> | Working directory |
-h, --help | Print help |
Examples
Basic Book
adrs generate book
This creates a book/ directory with:
book.toml- mdbook configurationsrc/SUMMARY.md- table of contentssrc/*.md- copies of all ADR files
Custom Output Directory
adrs generate book -o docs/decisions
Custom Title and Description
adrs generate book -t "Project Architecture" -d "Key decisions for the project"
Build and Serve
After generating:
adrs generate book
cd book
mdbook serve
Integration with CI
Generate and deploy the book automatically:
- name: Generate ADR book
run: |
adrs generate book
cd book && mdbook build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./book/book