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