---
title: 'Building Extensible Markdown & MDX Pipelines'
description: 'A deep dive into Unified, Remark, and Rehype plugins for custom documentation systems.'
subtitle: 'AST manipulation, syntax transformers, and custom directives.'
date: '2024-11-20'
lang: 'en'
---

The Unified and Comark ecosystems are immensely flexible abstractions for processing modern web markup[^ast]. By parsing source text into a compact abstract syntax tree, developers can manipulate nodes with modular plugins before rendering with modern UI frameworks.

## Pipeline Architecture

The processing lifecycle turns raw Markdown into rich, interactive components on the web[^plugins]:

```mermaid
graph TD
  A[Markdown Source] --> B[Comark Parser]
  B --> C[Plugin Pipeline]
  C --> D[Punctuation & Typography]
  C --> E[Footnote Collector]
  C --> F[Mermaid Diagram AST]
  D --> G[Unified Document AST]
  E --> G
  F --> G
  G --> H[React Server Components]
  H --> I[Hydrated Interactive UI]
```

## Typographic Refinements

With the typography plugin active, plain text punctuation is automatically converted into polished Unicode characters:

- "Smart quotes" and 'nested quotes' replace standard typewriter quotes.
- En-dashes (2024--2026) and em-dashes---used for parenthetical thoughts---are converted seamlessly.
- Trailing thoughts with ellipses... look balanced and intentional.
- Symbols like (c), (r), (tm), and +- 0.05 are normalized into standard glyphs.

## How AST Transformations Work

1. **Parse**: Markdown text -> `mdast` (Markdown Abstract Syntax Tree)
2. **Transform**: Remark & Comark plugins modify the tree in-flight
3. **Bridge**: Nodes are mapped to custom React components[^beautiful-mermaid]
4. **Compile**: RSC streams pristine markup directly to the client

```typescript
export function remarkCustomDirective() {
  return (tree) => {
    visit(tree, (node) => {
      if (node.type === 'textDirective' && node.name === 'badge') {
        node.data = {
          hName: 'span',
          hProperties: { className: ['badge-item'] },
        }
      }
    })
  }
}
```

[^ast]: An Abstract Syntax Tree (AST) represents the hierarchical syntactic structure of source code or markup.

[^plugins]: Comark plugins run during the markdown-it parsing phase or directly transform the Comark AST nodes.

[^beautiful-mermaid]: Diagrams are rendered using `beautiful-mermaid` with zero client-side DOM dependencies and native dark mode support.