Architecture Decision Records

Appearance

Replace Log4brains with VitePress for ADR Site Generation ​

  • Status: accepted
  • Deciders: [Development Team]
  • Date: 2026-02-20
  • Tags: dev-tools, doc

Context and Problem Statement ​

Log4brains, our ADR static site generator (adopted in 20250528), is unmaintained since 2021. Its internal webpack bundler cannot parse modern JavaScript syntax introduced by updated transitive dependencies (glob >= 10, minimatch >= 9). This causes the ADR pipeline build to fail, blocking CI/CD.

We need an alternative static site generator that:

  • Renders our existing MADR markdown files without modification
  • Provides sidebar navigation and search
  • Is actively maintained
  • Integrates with our Vite-based toolchain

Considered Options ​

  • VitePress
  • Docusaurus
  • Manual fix of Log4brains dependencies

Decision Outcome ​

Chosen option: VitePress, because it uses the same Vite build tool as our main application, is actively maintained, supports our markdown files as-is, and provides built-in search and sidebar navigation out of the box.

Positive Consequences ​

  • ADR pipeline builds are unblocked
  • Removes 29 transitive dependencies from log4brains
  • Aligns the ADR site tooling with our existing Vite stack
  • Developer workflow is unchanged (npm run adr:open, npm run adr:new)

Negative Consequences ​

  • One-time migration effort (~30 minutes)
  • VitePress config file to maintain (minimal)

Pros and Cons of the Options ​

VitePress ​

  • Good, because it's built on Vite (same as our app)
  • Good, because it's actively maintained with regular releases
  • Good, because it has built-in local search
  • Good, because it renders standard markdown with no custom syntax required
  • Good, because it has minimal configuration
  • Bad, because it doesn't have a dedicated ADR creation wizard (mitigated by a simple Node.js script)

Docusaurus ​

  • Good, because it has a large ecosystem and plugin support
  • Good, because it's maintained by Meta
  • Bad, because it uses webpack internally, adding a second bundler to the project
  • Bad, because it's heavier weight than needed for a simple ADR site

Manual fix of Log4brains dependencies ​

  • Good, because it requires no migration
  • Bad, because log4brains is unmaintained since 2021
  • Bad, because patching internal webpack config is fragile and unsustainable
  • Bad, because it doesn't resolve the root cause (old bundler incompatible with modern JS)