Boring engineering documentation that stays valid forever.
DocBoring is a minimal, deterministic toolchain for compiling internal RFCs, Architecture Decision Records (ADRs), and API runbooks into self-contained static HTML without client-side JavaScript runtimes or brittle theme dependencies.
Deterministic AST
Byte-for-byte reproducible HTML output across Linux, macOS, and CI runners using a pinned CommonMark parser.
Schema-Validated
Enforces YAML frontmatter ownership, status transitions, and cross-document link integrity before merging.
Zero-JS Output
Ships semantic HTML5 and a single 4 KB stylesheet. Readable in terminal browsers, offline archives, and 20-year backups.
Design Philosophy
Engineering teams rarely abandon documentation because they lack visual animations or full-text AI search widgets. They abandon documentation because build toolchains rot, relative links break silently, and ownership metadata drifts out of date.
DocBoring treats technical prose with the same rigor as compiled source code:
- Strict link verification — Broken internal anchors, missing ADR references, or unpinned external citations fail the build with non-zero exit codes.
- Explicit lifecycle metadata — Every specification carries an immutable identifier, owner handle, review date, and state machine transition (
draft,proposed,accepted,superseded). - Predictable filesystem layout — No magic routing plugins or hidden webpack caches; directory structure maps directly to output URLs.
Quickstart Guide
Install the standalone static binary or initialize a repository directly in an existing service codebase:
# Initialize a documentation workspace with strict ADR rules
mkdir -p engineering-docs && cd engineering-docs
docboring init --preset rfc-adr
# Validate frontmatter schemas, anchors, and canonical formatting
docboring check --strict
# Emit reproducible static HTML into ./dist
docboring build --out ./dist
Project Manifest (docboring.yaml)
Every repository declares a single top-level manifest specifying allowed document statuses, required metadata keys, and output base paths:
schema_version: 2
site:
title: "Core Platform Engineering RFCs"
base_url: "https://docboring.me"
language: "en"
input:
root: "./docs"
ignore:
- "**/archive/**"
- "README.md"
validation:
require_frontmatter: true
allowed_statuses: ["draft", "in-review", "accepted", "deprecated"]
enforce_unique_ids: true
check_relative_links: true
max_stale_days: 365
output:
dir: "./dist"
minify_html: false
emit_sitemap: true
Build Benchmarks
Measured on a single-core cloud instance compiling 1,200 CommonMark specifications with full AST link graph verification and syntax token generation:
| Corpus Size | Parse & AST Check | Link Graph Verify | HTML Emit | Peak RSS Memory |
|---|---|---|---|---|
| 100 documents | 14 ms | 3 ms | 9 ms | 11.4 MB |
| 500 documents | 61 ms | 12 ms | 38 ms | 24.8 MB |
| 1,200 documents | 142 ms | 27 ms | 89 ms | 46.2 MB |