Skip to content

Load mermaid from a CDN by default; --offline embeds it - #102

Merged
adamw merged 2 commits into
masterfrom
feat/mermaid-cdn
Nov 17, 2026
Merged

adamw merged 2 commits into
masterfrom
feat/mermaid-cdn

Conversation

@adamw

@adamw adamw commented Nov 17, 2026

Copy link
Copy Markdown
Member

The page was about 5.9 MB, and 5.5 MB of that is mermaid. Shared pages (ADR 0032) are stored on hidden refs that nothing prunes, so every preview adds that much.

What changes

  • By default the page loads mermaid from jsDelivr, at the version the build vendored. The page drops to about 350 KB plus its content.
  • --offline embeds mermaid as before, for pages that must work without network.
  • highlight.js, the fonts, the CSS and app.js stay embedded in both modes (about 0.3 MB together).

Safety

  • The script has an SRI integrity hash of the vendored bundle. jsDelivr serves npm files unchanged, so the build needs no network, and the browser refuses any other content.
  • The CSP allows that exact URL, not the whole host, so the page can't load any other file from jsDelivr.
  • The script is async, so a slow or blocked CDN doesn't hold up the rest of the page. If mermaid never loads, each diagram shows as source text.

Other changes

  • inline-assets.ts is renamed to page-assets.ts, since not every script is inlined any more.
  • The build writes the mermaid version to vendor/mermaid.version.
  • The CSP <meta> content is now HTML-escaped.
  • ADR 0033 records the decision; ADRs 0028, 0030 and 0032 and the README point to it.

Testing

  • tsc, pnpm lint and pnpm test pass (1136 tests).
  • Checked in headless Chrome:
    • the default page renders diagrams with no CSP errors;
    • --offline renders diagrams;
    • with no network or a wrong hash, diagrams show as source text;
    • other scripts from jsDelivr are blocked by the CSP.

Mermaid is 5.5 MB of the 5.9 MB page. By default the page now loads it from
jsDelivr at the vendored version, pinned by an SRI hash and allowed in the CSP
by its exact URL; the page drops to about 350 KB. --offline embeds it as before.
See ADR 0033.
A slow or blocked CDN held up app.js until the fetch timed out; the CDN script
is now async and app.js renders diagrams when it loads. The CSP meta content is
now HTML-escaped. Size figures live only in ADR 0033.
@adamw
adamw merged commit cb18c91 into master Nov 17, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant