API Reference

Quick reference for all MDC Syntax exports and APIs.

Core Parser (`mdc-syntax`)

Functions

`parse(source, options?)`

Synchronous parsing of MDC content.

import { parse } from 'mdc-syntax'

const result = parse(markdownContent, {
  autoUnwrap: true,  // Remove <p> wrappers from single-paragraph containers
  autoClose: true    // Auto-close incomplete syntax
})

// Returns: ParseResult
result.body   // MinimarkTree - Parsed AST
result.data   // any - Frontmatter data
result.toc    // TOC object
result.excerpt // Optional excerpt

`parseAsync(source, options?)`

Asynchronous parsing with optional syntax highlighting.

import { parseAsync } from 'mdc-syntax'

const result = await parseAsync(markdownContent, {
  highlight: true,
  // Or with options:
  highlight: {
    themes: { light: 'github-light', dark: 'github-dark' },
    languages: ['typescript', 'vue']
  }
})

`renderHTML(tree)`

Convert Minimark AST to HTML string.

import { renderHTML } from 'mdc-syntax'

const html = renderHTML(result.body)
// "<h1 id=\"hello\">Hello</h1><p>World</p>"

`renderMarkdown(tree)`

Convert Minimark AST back to markdown.

import { renderMarkdown } from 'mdc-syntax'

const markdown = renderMarkdown(result.body)
// "# Hello\n\nWorld"

`autoCloseMarkdown(source)`

Auto-close incomplete markdown/MDC syntax.

import { autoCloseMarkdown } from 'mdc-syntax'

autoCloseMarkdown('**bold')        // "**bold**"
autoCloseMarkdown('::alert\nText') // "::alert\nText\n::"

Stream Parser (`mdc-syntax/stream`)

Functions

`parseStream(stream, options?)`

Parse from a stream, returns when complete.

import { parseStream } from 'mdc-syntax/stream'

// Node.js stream
import { createReadStream } from 'node:fs'
const result = await parseStream(createReadStream('file.md'))

// Web stream (Fetch)
const response = await fetch('/content.md')
const result = await parseStream(response.body!)

`parseStreamIncremental(stream, options?)`

Real-time incremental parsing.

import { parseStreamIncremental } from 'mdc-syntax/stream'

for await (const result of parseStreamIncremental(stream)) {
  console.log(result.chunk)      // Current chunk
  console.log(result.body)       // Current AST state
  console.log(result.isComplete) // Stream finished?

  if (result.isComplete) {
    console.log(result.toc)      // Available when complete
  }
}

Types

`ParseResult`

interface ParseResult {
  body: MinimarkTree        // Parsed AST
  excerpt?: MinimarkTree    // Content before <!-- more -->
  data: any                 // Frontmatter data
  toc?: TOC                 // Table of contents
}

`IncrementalParseResult`

interface IncrementalParseResult extends ParseResult {
  chunk: string        // The chunk just received
  content: string      // The accumulated content
  isComplete: boolean  // Whether stream is finished
}

`ParseOptions`

interface ParseOptions {
  autoUnwrap?: boolean           // Remove unnecessary <p> wrappers (default: true)
  autoClose?: boolean            // Auto-close incomplete syntax (default: true)
  highlight?: boolean | ShikiOptions  // Enable syntax highlighting
}

`ShikiOptions`

interface ShikiOptions {
  themes?: Record<string, string>    // Theme configuration
  languages?: string[]               // Languages to preload
}

`MinimarkTree`

interface MinimarkTree {
  type: 'minimark'
  value: MinimarkNode[]
}

`MinimarkNode`

type MinimarkNode =
  | string  // Text node
  | [tag: string, props?: Record<string, any>, ...children: MinimarkNode[]]

`TOC`

interface TOC {
  title?: string
  depth: number
  searchDepth: number
  links: TOCLink[]
}

interface TOCLink {
  id: string
  text: string
  depth: number
  children?: TOCLink[]
}

Quick Import Reference

// Core parsing
import { parse, parseAsync, renderHTML, renderMarkdown, autoCloseMarkdown } from 'mdc-syntax'

// Stream parsing
import { parseStream, parseStreamIncremental } from 'mdc-syntax/stream'

// Vue components
import { MDC, MDCRenderer, ShikiCodeBlock } from 'mdc-syntax/vue'

// React components
import { MDC, MDCRenderer, ShikiCodeBlock } from 'mdc-syntax/react'

// Types
import type {
  ParseResult,
  ParseOptions,
  MinimarkTree,
  MinimarkNode,
  IncrementalParseResult,
  ShikiOptions
} from 'mdc-syntax'