Log4brains local preview setup and justfile task runner¶
- Date: 2026-03-26
- Status: Accepted
- Tags:
toolingworkflow
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:
- The
.log4brains.ymlconfig used an invalid schema —typeand top-levelpackagesare not recognized fields. The correct structure nestspackagesunderprojectand requirestzandadrFolderat the project level. - ADR template files (
_template.md) were rendered as DRAFT entries in the sidebar and caused "unexpected error" pages when clicked. - Two ADRs shared the
0009prefix (aws-investigator-skill and tflint-ruleset-trusty-custom-plugin), creating a collision. - There was no task runner — developers had to remember
npx log4brains previewand manually manage port conflicts. - 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.ymlwithtz,adrFolderat the project level, andpackagesnested underproject - Template rename: rename
_template.mdtotemplate.mdin bothdecisions/andobsidian/decisions/— log4brains reservestemplate.mdand auto-ignores it, while_template.mdis treated as a regular ADR - ADR renumbering: rename
0009-tflint-ruleset-trusty-custom-plugin.mdto0017to resolve the duplicate prefix - Homepage: add
decisions/index.mdas the log4brains landing page - Justfile: add a
justfilewithpreview,build,lint, andadr-newcommands —just previewkills 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 previewprovides 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
/adrskill
Negative / Trade-offs:
justmust 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.