Skip to content

Log4brains local preview setup and justfile task runner

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

Context

After adopting log4brains for ADR publishing (ADR 0016), the local preview experience had several issues that needed resolution before the repo could go public with GitHub Pages:

  1. The .log4brains.yml config used an invalid schema — type and top-level packages are not recognized fields. The correct structure nests packages under project and requires tz and adrFolder at the project level.
  2. ADR template files (_template.md) were rendered as DRAFT entries in the sidebar and caused "unexpected error" pages when clicked.
  3. Two ADRs shared the 0009 prefix (aws-investigator-skill and tflint-ruleset-trusty-custom-plugin), creating a collision.
  4. There was no task runner — developers had to remember npx log4brains preview and manually manage port conflicts.
  5. The CI markdown lint workflow did not exclude .claude/ agent files, causing failures on pre-existing content. A new MD060 rule also flagged all existing tables in the repo.

Decision

We will fix the log4brains configuration and add a justfile for local development tasks:

  • Config fix: restructure .log4brains.yml with tz, adrFolder at the project level, and packages nested under project
  • Template rename: rename _template.md to template.md in both decisions/ and obsidian/decisions/ — log4brains reserves template.md and auto-ignores it, while _template.md is treated as a regular ADR
  • ADR renumbering: rename 0009-tflint-ruleset-trusty-custom-plugin.md to 0017 to resolve the duplicate prefix
  • Homepage: add decisions/index.md as the log4brains landing page
  • Justfile: add a justfile with preview, build, lint, and adr-new commands — just preview kills any existing server on port 4004, opens the browser, and starts log4brains
  • CI fixes: add !.claude/** exclusion to the markdown lint workflow and disable MD060 (table-column-style) globally

All references to _template.md were updated across CLAUDE.md, README.md, the /adr skill, and the adr-check.yml CI workflow.

Alternatives Considered

Option Why Rejected
Makefile instead of justfile Makefile requires .PHONY boilerplate and tab-sensitivity; justfile has cleaner syntax for a task runner
Delete template files entirely Templates are referenced in docs and CI — they serve as the canonical ADR scaffold
Add .log4brainsignore log4brains has no ignore config; the reserved filename approach is the supported mechanism
Dockerize the preview Unnecessary overhead for a simple Node.js static site generator

Consequences

Positive:

  • just preview provides a one-command local ADR site preview
  • No more ghost DRAFT entries or error pages in the sidebar
  • CI passes cleanly on all current content
  • Template files remain usable for ADR creation via the /adr skill

Negative / Trade-offs:

  • just must be installed (brew install just) — not a standard tool
  • MD060 is globally disabled rather than fixing all existing tables

Ongoing obligations:

  • Keep justfile commands in sync with any log4brains config changes
  • If markdownlint-cli2 is upgraded in CI, verify the hardcoded exclusion list still matches .markdownlintignore

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