DOC-6873 Fix slow Hugo builds

[andy-stark-redis]

What & why

The Hugo build had regressed to ~10+ minutes. Investigation (hugo --templateMetrics) traced it to layouts/partials/tabs/source.html re-running Chroma over the entire source file on every slice, every step, and every page — 3,000+ uncached highlights, the single most expensive thing in the build.

Two changes:

1. Cache the full-file highlight. New layouts/partials/tabs/highlight-file.html does the read+highlight and is called via partialCached keyed on (file, language, options), so each file is highlighted once per build instead of once per slice/step/page. source.html now slices the cached HTML.

   • 95% cache-hit rate, syntax-highlight user-CPU down ~27% (4m31s → 3m19s).
   • Proven byte-neutral on every content page (fixed-vs-baseline diffs equal the build's own run-to-run noise floor).

2. Fix a pre-existing nondeterminism it uncovered. The tce-fullsrc full-file <template> dedup in tabbed-clients-example.html tracks its "seen" set in .Page.Store, which persists across a page's output-format renders. Hugo's internal RSS renders each item's full .Content, re-executing the page's shortcodes in a second render that shares that store and races the HTML render. On the heavy develop/data-types/streams/ page this meant the served HTML intermittently shipped 8 or 0 full-source templates (i.e. the "view full file" affordance was randomly broken). New layouts/_default/rss.xml sources item descriptions from front matter instead of rendering .Content, so content shortcodes never run during RSS. Emission is now deterministic for every page.

⚠️ Reviewer callout — RSS behaviour change

RSS feeds now carry each item's front-matter description (falling back to title) instead of the full rendered page HTML. This is the mechanism of fix #2 (and is normal/lighter for feeds), but it is an outward-facing change to feed content — flagging it explicitly.

Verification

Two consecutive full builds, exit 0, no template errors:

	build 1	build 2
streams full-source templates	8	8 (deterministic)
sorted-sets (control)	11	11 (unchanged)
data-types RSS items / rendered-code-in-RSS	7 / 0	7 / 0
RSS well-formed (xmllint)	OK	—

Wall-clock speedup is not claimed as a hard number: the benchmark machine was I/O-bound (builds swung 5–16 min dominated by system time), so only the user-CPU reduction is trustworthy.

Ticket: DOC-6873

🤖 Generated with Claude Code

---

Note

Medium Risk
Build output and RSS item descriptions change in user-visible ways (feeds lose full HTML bodies); HTML for examples is intended to stay byte-neutral but the RSS behaviour is an explicit outward-facing change.

Overview
Speeds up Hugo builds by caching full-file Chroma output for tabbed client examples instead of re-highlighting the same source on every slice, step, and page.

tabs/source.html now pulls a single highlighted file via partialCached on new tabs/highlight-file.html (keyed by path, language, and options) and only slices that HTML when a line range is needed. Fixes intermittent missing “view full file” templates on pages with many clients-example shortcodes.

A custom layouts/_default/rss.xml stops rendering each item’s full .Content in the RSS pass. Item descriptions come from front matter (description or title) only, so RSS no longer re-runs those shortcodes and races HTML for .Page.Store (tceFullKeys). RSS feed text changes from full page HTML to short summaries—that’s intentional and the mechanism of the determinism fix.

^{Reviewed by Cursor Bugbot for commit b249f9f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

DOC-6873

[dwdougherty]

I tried to test this locally, but I kept hitting rate limits on the client library sites. Approving anyway, because it's a new world now.

[andy-stark-redis]

@dwdougherty You could do make localserve maybe, if you've got the repo folders set up? Thanks for the review, anyway :-)