Braised Docs

Performance

Braised Docs is designed to be fast for typical documentation sites. This page documents known scaling characteristics and the design decisions made to address them.

The sidebar navigation is rendered once per build and reused across all pages (a pattern borrowed from Hugo's partialCached). The pre-rendered HTML string is injected into each page's template directly, bypassing per-page template execution.

Active-link state (highlighting the current page in the sidebar) is applied client-side by blocks.js after the page loads. This avoids the need for per-page nav variants while preserving correct behavior for users without JavaScript — the nav is fully visible and navigable, just without a highlight on the current entry.

Large nav trees

If your nav tree is very large — hundreds or thousands of entries — the nav HTML string itself becomes large, and embedding it verbatim in every output page multiplies the total build output proportionally.

For example, the PostgreSQL documentation converted from DocBook has roughly 1,000 pages and a corresponding 1,000-entry nav tree. Each output page embeds ~200 KB of nav HTML, producing ~200 MB of total output. On a fast filesystem (tmpfs, NVMe) this is not an issue. On ext4 with journaling, rewriting that volume of existing files adds significant I/O overhead even though the content is the same — clean builds to an empty output directory remain fast.

Practical advice:

  • If you are building a very large site on ext4 and subsequent builds are slow, try building to a tmpfs location (e.g. /tmp/dist) and syncing to the real output path only for deployment. Clean builds are always fast.
  • If your nav has hundreds of entries but your content is hierarchical, consider whether a shallower nav with section landing pages would serve readers better than a flat list of all pages. Smaller navs benefit both build performance and the reader experience.

Typical documentation sites (tens to low hundreds of pages) are not affected by any of this.

Build parallelism

Page rendering is parallelized across a pool of workers (one worker per available CPU core by default). Goldmark parsing, block rendering, and template execution all happen concurrently per page.

The nav pre-rendering step, ref index construction, and CSS/JS bundling happen once before the parallel page phase begins.

Profiling

The braised build command accepts --cpuprofile and --memprofile flags for Go's standard pprof tooling:

braised build --cpuprofile cpu.prof
go tool pprof cpu.prof

The most useful pprof commands for build profiling are top (flat/cumulative CPU) and web (flame graph, requires Graphviz).