Add Mermaid Charts to Our Extended Markdown

Changelog Entry: Mermaid Chart Expand/Collapse Refactor

Summary

Built and integrated a new extended markdown feature: a Mermaid Chart component system from scratch. Applied site-specific theme, and introduced expand/collapse functionality using a pure HTML/CSS approach for icon toggling, alongside robust fullscreen modal capabilities. This work enables our technical documentation and Vibe Coding libraries to be more interactive and meaningful.

Why Care:

Technical documentation and visual programming are becoming MORE important because of the rise of AI Code Assistants and Code Generators. Simply put, AI can only be as good as the instruction set it is given. In addition, because AI can generate code so rapidly, and it can overwrite and refactor code that has unintended consequences, it becomes critical to have a "Source of Truth" that you can constantly go back to.

Details

New component: MermaidChart.astro
  • Architecture Overview:
    • @site/src/layouts/OneArticle.astro
      • Top-level layout for rendering a single article in a centered, readable format.
      • Handles markdown content parsing using a unified processor with custom remark plugins (e.g., backlinks, images, citations).
      • Parses markdown to MDAST, applies transformations, and passes the transformed AST as the content prop to the next component.
      • Debug utilities log and write the transformed AST for transparency and troubleshooting.
      • Renders the markdown content by passing it to the Component prop (usually AstroMarkdown.astro).
    • @site/src/components/markdown/AstroMarkdown.astro
      • Core recursive renderer for markdown AST nodes.
      • Handles all major MDAST node types (root, heading, paragraph, list, link, code, etc.) with explicit branching for each.
      • For code blocks with lang: "mermaid", renders the MermaidChart.astro component, passing the diagram code.
      • Ensures modularity and extensibility by delegating special node types (callouts, citations, footnotes, etc.) to their own components.
      • Maintains accessibility and semantic HTML throughout the rendering process.
    • @site/src/components/codeblocks/MermaidChart.astro
      • Specialized component for rendering Mermaid diagrams.
      • Receives the diagram code as a prop from AstroMarkdown.astro.
      • Implements pure HTML/CSS expand/collapse toggle for chart display, with accessible ARIA labeling and keyboard navigation.
      • Provides fullscreen modal logic for immersive chart viewing, injected dynamically and decoupled from the toggle.
      • Applies site-specific theme and style customizations to Mermaid charts, ensuring visual consistency.
      • Loads Mermaid.js dynamically and initializes with a custom configuration for seamless integration.
  • This architecture enables:
    • Seamless authoring of complex technical diagrams in markdown.
    • Modular, maintainable, and extensible rendering pipeline.
    • Accessibility and modern UI/UX best practices at every layer.
    • Debuggability and transparency through AST logging and debug utilities.

Motivation

  • Previous implementations relied too heavily on JS for UI state, leading to hydration issues and user frustration.
  • The new approach is more robust, accessible, and maintainable, and aligns with modern UI/UX standards for toggle controls.
  • bbab96b: Refactor Mermaid chart expand/collapse logic and globalize modal styles
  • 3e97c16: Citations and Mermaid charts now both work in this branch
  • 5112734: Working Mermaid charts with 10 lines of code

Next Steps

  • Optionally wire the checkbox toggle to trigger fullscreen modal logic for a fully integrated experience.
  • Continue to monitor for cross-browser and device compatibility.
This entry was generated following the workflow: Write-a-Code-Changelog-Entry.