Skip to content

Adopt log4brains to publish ADRs as a GitHub Pages site

  • Date: 2026-03-26
  • Status: Accepted
  • Tags: tooling workflow

Context

ADRs in this repository live across two directories (decisions/ and obsidian/decisions/) and are currently only accessible to people who clone the repo or browse GitHub's file tree. There is no rendered, searchable view of the decision history. As the number of ADRs grows, discoverability and cross-referencing becomes harder.

A lightweight publishing step that converts the Markdown ADRs into a navigable static site — deployed automatically on push to main — would make the decision log more accessible without adding ongoing maintenance overhead.

Decision

We will adopt log4brains (1.1.0) to build and deploy the ADR corpus as a GitHub Pages site.

Key design choices:

  • Multi-package mode — .log4brains.yml configures two packages (repo pointing at decisions/ and obsidian pointing at obsidian/decisions/) so both ADR sequences appear in the same published site.
  • No format migration — existing ADRs will NOT be converted to MADR format. The ADR immutability rule takes precedence. log4brains will render them as-is; status fields it cannot parse will show as "unknown", which is acceptable and documented here.
  • GitHub Actions deployment — a new pages-deploy.yml workflow runs npm run build and deploys via actions/upload-pages-artifact + actions/deploy-pages on every push to main.
  • GitHub Pages must be enabled manually — in the repository settings, navigate to Pages → Source and select "GitHub Actions" as the deployment source. This one-time step is required before the workflow will succeed.

Alternatives Considered

Option Why Rejected
Raw GitHub Pages + Jekyll Requires manual front-matter on every ADR and a custom Jekyll theme; higher ongoing maintenance.
ADR Tools (adr-log) Generates only a flat changelog, not a navigable UI with search.
Backstage TechDocs Significant infrastructure overhead; overkill for a single-repo decision log.
No publishing (status quo) ADRs remain buried in the file tree; discoverability does not improve.

Consequences

Positive:

  • ADRs are browsable and searchable at the GitHub Pages URL without cloning the repo.
  • Deployment is fully automated — merging to main triggers the build and deploy.
  • No ongoing maintenance of the site itself; log4brains handles rendering.

Negative / Trade-offs:

  • Existing ADRs will show "unknown" status in the log4brains UI because they do not use MADR <!-- status: ... --> markers. This is intentional (immutability rule) and acceptable.
  • A package.json and node_modules/ are introduced at the repo root; this is a docs-only repo so no application code conflicts exist, but it adds a Node.js dependency footprint.
  • GitHub Pages must be manually enabled in repo settings once before the first deployment succeeds.

Ongoing obligations:

  • Pin and periodically update the log4brains version in package.json.
  • Keep node_modules/ and log4brains-out/ in .gitignore.

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.