ArchDoc design record

Architecture

cmd/archdoc is the only package that imports cobra. No package under internal/ prints, prompts, or calls os.Exit; each is usable without a terminal. Every comma...

Commands

Every command except init locates archdoc.json by walking up from the working directory and fails if none is found. -C <dir>, --chdir <dir>, is a persistent fla...

Documents

A document is a Markdown file with a YAML front matter block. There are six types: RFC, ADR, spec page, ref, term and group. Each type lives in its own director...

Export

archdoc export writes the repository as JSON on stdout. --out <dir> writes a tree of files instead. --no-bodies omits every body, of contents entries, questions...

Index

archdoc index generates INDEX.md under root and prints the path written. With --check, it generates to memory and compares the result with the file on disk: whe...

Layout

A specification repository is a directory containing archdoc.json and, under root, the document directories. group/ is optional, and init does not create it.

Lifecycle

RFCs and ADRs have a status. Spec pages and refs do not.

Links and the glossary

[[X]] in a body marks a link to be filled in. archdoc link replaces each one in every document that is not frozen with a Markdown link: If X is an identifier:...

Lint

archdoc lint runs every L rule over every document and prints findings. With --merge it also runs the merge rules. Exit code 2 if any error, 0 otherwise. Warnin...

Markdown

The body of a document is everything after the closing --- of the front matter. The tool reads headings, HTML comments, code blocks, HTML blocks and links throu...

Relationships

Front matter records forward relationships: depends, updates and obsoletes on an RFC or ADR, includes on a spec page, and documents on a group. Every reverse re...

Release

Tagged versions build with goreleaser for linux, darwin and windows on amd64 and arm64. Archives are tar.gz, or zip for windows, named archdoc_<version>_<os>_<a...