← Corpus / lost-in-public / exploration

Render AST in Debug

Exploration of AST structure at each stage of markdown processing to understand how to handle callouts

Path
explorations/Render-AST-in-Debug.md
Authors
Michael Staton
Augmented with
Windsurf Cascade on Claude 3.5 Sonnet
Tags
Remark · Astro · AST · Debug

Objective

Before implementing callout rendering, we need to understand exactly how the AST looks at each stage of processing. This exploration will:

  1. Add debug logging to show the AST structure:

    • After initial markdown parsing
    • After each remark plugin
    • After rehype conversion
    • Before final HTML rendering
  2. Focus on understanding:

    • How blockquotes are represented in the AST
    • Where callout syntax appears in the node structure
    • What node types we need to work with
    • Best points to intercept for transformation
  3. Create a clean baseline without any transformation logic:

    • Remove existing callout handling code
    • Add comprehensive debug output
    • Document the AST structure at each stage

Implementation Plan

  1. Remove existing callout transformation code
  2. Add debug logging to [vocabulary].astro
  3. Add debug logging to each remark plugin
  4. Create test markdown files with various callout patterns
  5. Document the AST structure we observe

Success Criteria

  • Clear visibility of AST at each processing stage
  • Understanding of where callout syntax appears
  • Documentation of node types and structure
  • Clean baseline for implementing new transformation approach