Enhanced Markdown Footnotes, Citations, and Mermaid Rendering

Summary

Improved rendering of footnoteReference, footnoteDefinition, and custom citation nodes in Astro markdown layouts. Introduced Mermaid.js support for code blocks with language mermaid, styled for dark mode, and added a header to the ArticleCitationsBlock.

Why Care

These changes significantly enhance document readability and navigability, particularly for academic or research-style writing. Users now benefit from inline footnotes, backlinking for definitions, dark-mode Mermaid graphs, and consistent citation presentation.

Implementation

Changes Made

  • Added return links (↩) from footnoteDefinition back to corresponding footnoteReference
  • Ensured inline rendering of footnote definitions when they contain only a single paragraph
  • Updated AstroMarkdown.astro to:
    • Detect and render code blocks with lang: "mermaid" using a new component
    • Route Mermaid blocks to components/codeblocks/MermaidChart.astro
  • Created MermaidChart.astro:
    • Lazy-loads Mermaid.js from CDN
    • Automatically renders charts on page load
    • Defaults to dark theme based on static config
  • Updated components/citations/ArticleCitationsBlock.astro to include a heading: Footnotes and Citations

Technical Details

  • File: components/codeblocks/MermaidChart.astro
astro 
<div class="mermaid">
  {code}
</div>

<script is:inline>
  import('https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs')
    .then(m => {
      m.default.initialize({ startOnLoad: true, theme: 'dark' });
      m.default.run();
      window.mermaid = m.default;
      window.__MERMAID_LOADED__ = true;
    });
</script>