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>