Custom Markdown Renderer: Citation, Table, List, Image, and Code Support

Summary

Identified 3 places where markdown was being parsed into MDAST or HTML, consolidated this all to one unified function in OneArticle.astro. Was able to cut dozens of lines of config. Enhanced the Astro-based Markdown rendering pipeline to support fully customized rendering of tables, images, code blocks, lists, inline citations, and footnotes using MDAST parsing and hand-built components. Improvements include structured AST transforms, styling hooks, citation extraction and reorganization, and clean semantic HTML output.

Why Care

This update significantly improves the quality and functionality of rendered Markdown content across the site. Lists display with consistent custom markers, tables appear styled and readable, inline code and block code are semantically and visually distinguished, and citations mimic Wikipedia-style footnotes. All of this enables better UX and richer article formatting without relying on third-party plugins or brittle HTML hacks.

Implementation

Changes Made

  • /src/components/markdown/AstroMarkdown.astro
    • Introduced per-node type handling via Astro.self
    • Added support for rendering:
      • Lists (list, listItem)
      • Tables (table, tableRow, tableCell)
      • Code blocks (code, inlineCode)
      • Images (image)
      • Thematic breaks (thematicBreak)
      • Paragraphs and text nodes (paragraph, text)
      • Custom citations and citation node types
  • /src/utils/markdown/remarkCitations.ts
    • Extracted single-line citation entries ([n] https://...)
    • Added logic to convert inline [n] into clickable footnote references
    • Appended citations section at the end of the document with return links
    • Added support for links like <a href="#cite-n">[n]</a> and <a href="#ref-n">[n]</a>
  • /src/components/markdown/styles.css (or inlined <style> blocks)
    • Added .markdown-table, .custom-li, .inline-code, and .code-block classes
    • Added borders and spacing to table cells
    • Styled inline citation links and their targets
    • Ensured consistent typography and spacing for paragraphs, lists, and headers

Technical Details

Table Rendering

javascript 
{(node.type === \"table\") && (
  <div class=\"table-wrapper\">
    <table class=\"markdown-table\">
      <tbody>
        {node.children.map(row => (
          <Astro.self node={row} data={data} />
        ))}
      </tbody>
    </table>
  </div>
)}