Render Mermaid diagrams on the docs site #14
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "initial-development"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Workspace setup:
packages/*
scripts
out of docs-site/ scope to cover the whole workspace
@nullified/mermaid-viewer (new package at packages/mermaid-viewer):
svg-pan-zoom runtime dep (-38KB; supports wheel
zoom, click-drag, two-finger pinch, keyboard
pan/zoom)
instead of a 500ms x 30 polling loop, so the viewer
attaches the moment Mermaid drops in the SVG
before the host renderer replaces it with SVG, so
orientation-swap and fullscreen re-render have a
source to work with regardless of whether the host
sets data-mermaid-source
package-owned --mermaid-viewer-* CSS custom
properties for theming overrides; buttons declare
all: unset+ explicit inline-flex + line-height: 0so high-specificity host content rules can't push
them off-baseline
prefers-color-scheme fallback + explicit
[data-mermaid-viewer-theme="light"] override; the
package owns its own attribute name so the CSS
doesn't need to know about Starlight's data-theme,
Tailwind's .dark, etc.
onto each wrapper as data-mermaid-viewer-theme;
fullscreen overlay picks up the same attribute at
construction
fullscreen overlay traps Tab focus and closes on
Esc
selector overrides the standalone height cap in
the fullscreen path (the box and the viewer are the
same element there)
wrapperClassoption on enhanceAll lets consumersadd framework-specific opt-out classes to each wrapper
without polluting the package with framework
knowledge
utilities (38 tests across pastel-swap idempotency,
orientation swaps, and theme-observer behaviour)
src/index.ts, no tsup build, Vite compiles TS during
the consumer build
bundled in; consumers override visuals via the CSS
custom properties
docs-site integration:
pastel adaptive themeVariables so the existing
architecture/overview diagrams render in our palette
loads the viewer stylesheet, and runs enhanceAll on
every page with wrapperClass: "not-content" so
Starlight's sibling-margin rules leave the toolbar
layout alone
and the workspace dep on @nullified/mermaid-viewer
Build infra:
workspace root and runs
pnpm --filter guitar-prometheus-docs-site buildfragmented-infra/public-sites/Dockerfile to mirror the
new install layout)
Wishlist:
per the shipped-equals-remove policy; the
implementation plan at
documentation/agentic-context/implementation-plans/
2026-05-29-mermaid-rendering.md is the permanent
record
New Files:
2026-05-29-mermaid-rendering.md
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
Workspace setup: - pnpm-workspace.yaml at repo root listing docs-site + packages/* - Top-level package.json holds pnpm config + workspace scripts - .gitignore moves node_modules / pnpm-lock.yaml rules out of docs-site/ scope to cover the whole workspace @nullified/mermaid-viewer (new package at packages/mermaid-viewer): - Seeded from a curated upstream library, then optimized: - Native pointer-events pan/zoom replaces the svg-pan-zoom runtime dep (-38KB; supports wheel zoom, click-drag, two-finger pinch, keyboard pan/zoom) - Bootstrap uses per-target MutationObservers instead of a 500ms x 30 polling loop, so the viewer attaches the moment Mermaid drops in the SVG - Source capture from each container's textContent before the host renderer replaces it with SVG, so orientation-swap and fullscreen re-render have a source to work with regardless of whether the host sets data-mermaid-source - Inline JS styles moved to src/styles.css with package-owned --mermaid-viewer-* CSS custom properties for theming overrides; buttons declare `all: unset` + explicit inline-flex + line-height: 0 so high-specificity host content rules can't push them off-baseline - Frame tokens split into dark defaults + prefers-color-scheme fallback + explicit [data-mermaid-viewer-theme="light"] override; the package owns its own attribute name so the CSS doesn't need to know about Starlight's data-theme, Tailwind's .dark, etc. - Theme observer propagates the resolved host theme onto each wrapper as data-mermaid-viewer-theme; fullscreen overlay picks up the same attribute at construction - Toolbar buttons get aria-label + focus-visible; fullscreen overlay traps Tab focus and closes on Esc - Compound .mermaid-viewer-overlay__content.mermaid-viewer selector overrides the standalone height cap in the fullscreen path (the box and the viewer are the same element there) - New `wrapperClass` option on enhanceAll lets consumers add framework-specific opt-out classes to each wrapper without polluting the package with framework knowledge - Vitest + jsdom test suite for the source-transformation utilities (38 tests across pastel-swap idempotency, orientation swaps, and theme-observer behaviour) - Source-only consumption: package.json main points at src/index.ts, no tsup build, Vite compiles TS during the consumer build - Fully framework-agnostic: no host-framework defaults bundled in; consumers override visuals via the CSS custom properties docs-site integration: - astro-mermaid registered first in integrations with pastel adaptive themeVariables so the existing architecture/overview diagrams render in our palette - MermaidEnhanceHead.astro overrides Starlight's Head, loads the viewer stylesheet, and runs enhanceAll on every page with wrapperClass: "not-content" so Starlight's sibling-margin rules leave the toolbar layout alone - docs-site/package.json adds astro-mermaid, mermaid, and the workspace dep on @nullified/mermaid-viewer Build infra: - scripts/preview-docs-site.sh now installs at the workspace root and runs `pnpm --filter guitar-prometheus-docs-site build` - (Sibling change pending in fragmented-infra/public-sites/Dockerfile to mirror the new install layout) Wishlist: - Remove the "Mermaid rendering on the docs site" entry per the shipped-equals-remove policy; the implementation plan at documentation/agentic-context/implementation-plans/ 2026-05-29-mermaid-rendering.md is the permanent record New Files: - packages/mermaid-viewer/{src,tests}/* (full package) - docs-site/src/components/MermaidEnhanceHead.astro - pnpm-workspace.yaml, package.json - documentation/agentic-context/implementation-plans/ 2026-05-29-mermaid-rendering.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>