Markdoc

Stripe's structured markdown toolkit. Tag-based syntax with schema validation. Framework-agnostic rendering.

Markdoc Source
Rendered Output

How It Works

typescript 
import Markdoc from '@markdoc/markdoc';

const source = `
# Hello {% badge text="New" /%}

{% callout type="warning" %}
Important information here.
{% /callout %}
`;

// 1. Parse — source → AST
const ast = Markdoc.parse(source);

// 2. Validate — check against schema
const errors = Markdoc.validate(ast, config);

// 3. Transform — AST → renderable tree
const content = Markdoc.transform(ast, config);

// 4. Render — to HTML, React, or any framework
const html = Markdoc.renderers.html(content);

Key Features

  • Tag syntax — {% tag %} blocks for structured content (callouts, tabs, badges)
  • Schema validation — validate content structure, required attributes, allowed nesting
  • Variables — {% if $isAdmin %} for conditional content
  • Functions — custom functions callable in content
  • Framework-agnostic — render to HTML, React, Vue, or any framework
  • Parse → Validate → Transform → Render pipeline

Strengths

  • Schema validation ensures content quality
  • Framework-agnostic rendering
  • Clean pipeline (parse → validate → transform → render)
  • Great for documentation sites
  • Stripe-backed, production-proven
  • Custom tags for structured content

Weaknesses

  • Non-standard syntax (learning curve for authors)
  • Smaller community than remark/rehype
  • Not compatible with existing markdown tools
  • Tag syntax can feel verbose