Prettify mermaid diagram rendering

[irvinebroque]

• agents increasingly consume our documentation
• mermaid diagrams are easier for language models to parse and understand than static images
• Mermaid's text-based format allows models to extract relationships, flows, and architectural patterns
• Mermaid diagrams lacked proper styling and didn't meet the visual polish expected in our documentation

This PR enhances mermaid diagram rendering with:

• Cloudflare branding: Custom theme using our brand orange (#f6821f) and color palette (cl1-orange, cl1-gray)
• Light/dark theme support: Automatic re-rendering when users switch themes
• Annotation footers: Professional footer with diagram title (from accTitle) and Cloudflare logo
• Improved typography: Uses Starlight's font stack for consistency
• Better accessibility: Proper contrast ratios and support for screen reader descriptions (accDescr)

Examples

Before:

After:

Notes

Why some values are hardcoded: The styling logic currently lives in TypeScript (src/scripts/mermaid.ts) since mermaid's theme configuration requires JavaScript initialization. Hex codes and specific style values are hardcoded for:

• Theme variables (primaryColor, borderColor, etc.)
• Cloudflare brand colors (cl1-orange-9, cl1-gray-0, etc.)
• Font family extracted from CSS variables

This seemed like the simplest starting point. If there's a better approach to make these values more maintainable (e.g., extracting to a config file or reading more from CSS custom properties), I'm open to refactoring.

Files changed

• src/scripts/mermaid.ts: Enhanced rendering with custom theme variables, wrapper containers, and annotation footers
• src/styles/mermaid.css: Container styles, annotation footer styling, dark mode adjustments
• src/scripts/MERMAID.md: New documentation for usage, customization, and troubleshooting

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*	@cloudflare/pcx-technical-writing
*.ts	@cloudflare/pcx-content-engineering, @cloudflare/content-engineering, @kodster28

[github-actions]

Preview URL: https://c071c67c.preview.developers.cloudflare.com
Preview Branch URL: https://bib-mermaid.preview.developers.cloudflare.com

[irvinebroque]

@cloudflare/pcx-content-engineering thoughts? would love to land this

[colbywhite]

Given the state of our mermaid integration (custom fork, client-side focused), this is likely the most straightforward way to get the custom theme in there. Ideally, Cloudflare's theme(s) would be represented via something like style-dictionary to avoid the hardcoding. Let's merge it for now. I've got comments that may or may not need to be easy to address.

[colbywhite]

Sidenote: I don't think this comment is 100% accurate. Instead of a quick shift from the raw diagram text to the svg, this opts for a quick shift from nothing to the svg. Both strategies still flash and result in CLS. This seems like a purposeful decision and thus a bit orthogonal to this PR, but the comment implies that this is preventing any flash.

[colbywhite]

Any reason this is needed at the root level?

[colbywhite]

Is this meant to be a general "How to do mermaid" doc? The accTitle and accDesc recommendation likely makes more sense in the style guide, although I'm not sure where. We might need to create a good spot for it. The rest might be better served in the contributing page in some shape or form.

This loose md file might get lost.