ADR 0012: Shared Theme Asset Caching for Multi-Site CDN¶

2026-08-19

Status¶

Proposed

Date¶

2026-08-06

Context¶

23 mkdocs sites share identical Material theme assets (67 JS/CSS/font files per site). Stored redundantly in COS; re-downloaded by each visitor. Sites must remain self-contained per repo, but CDN-level sharing is acceptable since assets are byte-identical across all sites using the same theme version.

Decision¶

Each site builds independently (self-contained). EdgeOne CDN rewrites theme asset URLs to a shared cache domain.

Site A builds → /assets/js/bundle.js (abc123)
Site B builds → /assets/js/bundle.js (abc123, identical)
                    │
                    ▼
          EdgeOne CDN URL rewrite:
          /assets/javascripts/* → https://assets.omnivoltaic.cn/mkdocs/9.5/js/*
                    │
                    ▼
          Shared cache — served once, cached globally (1yr TTL)

Deploy when 5+ sites are live. Until then, overhead is trivial (~2MB/site).

Per-Site Delta¶

Metric	Before	After
Files per build	89	89 (unchanged — self-contained)
CDN cache misses	89	~22 per cold start
Bandwidth	N × 67 per deploy	67 once, forever cached

Consequences¶

Zero code changes — each repo builds identically, self-contained
One EdgeOne config — URL rewrite + shared cache bucket
1-year cache TTL — theme assets immutable per mkdocs version
Deferred trigger — deploy when 5+ sites active
Asset sharing across subdomains (docs, decks, memo, training, media)