API Reference

Cheat Sheet

Parse APIRender API
Quick reference for all Comark exports, types, and APIs across all packages.

comark (Core)

parse(source, options?)

Parse Comark content into a ComarkTree.

import { parse } from 'comark'
import highlight from 'comark/plugins/highlight'

const result = await parse(source, {
  autoUnwrap: true,   // Remove <p> wrappers from single-paragraph containers
  autoClose: true,    // Auto-close incomplete syntax
  html: true,         // Parse embedded HTML tags into AST nodes
  plugins: [highlight()]
})

result.nodes         // ComarkNode[]: parsed AST nodes
result.frontmatter   // Record<string, any>: frontmatter data
result.meta.toc      // TOC object (from toc plugin)
result.meta.summary  // ComarkNode[] (from summary plugin)

createParse(options?)

Creates a reusable parser initialized once, more efficient for batch processing.

import { createParse } from 'comark'

const parse = createParse({ plugins: [highlight()] })

const tree1 = await parse('# Document 1')
const tree2 = await parse('# Document 2')

renderMarkdown(tree, options?)

Convert a ComarkTree back to a markdown string.

import { renderMarkdown } from 'comark/render'

const markdown = await renderMarkdown(tree, {
  maxInlineAttributes: 3,  // Switch to YAML block syntax above this threshold
})

autoCloseMarkdown(source)

Close unclosed markdown syntax and Comark components. Useful for streaming.

import { autoCloseMarkdown } from 'comark'

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

String Renderers

@comark/html

render(markdown, options?)

Parse and render markdown to an HTML string in one call.

import { render } from '@comark/html'

const html = await render('# Hello\n\nThis is **bold**.')

createRender(options?)

Creates a reusable parse+render function initialized once.

import { createRender } from '@comark/html'

const render = createRender({
  parse: { plugins: [highlight()] },
  render: {
    components: {
      alert: async ([, attrs, ...children], { render }) =>
        `<div class="alert-${attrs.type}">${await render(children)}</div>`
    }
  }
})

const html = await render(source)

renderHTML(tree, options?)

Render a pre-parsed ComarkTree to an HTML string.

import { renderHTML } from '@comark/html'

const html = await renderHTML(tree, {
  components: {
    alert: async ([, attrs, ...children], { render }) =>
      `<div class="alert-${attrs.type}">${await render(children)}</div>`
  }
})

@comark/ansi

render(markdown, options?)

Parse and render markdown to an ANSI-styled terminal string in one call.

import { render } from '@comark/ansi'

const output = await render('# Hello\n\nThis is **bold**.')
process.stdout.write(output)

renderANSI(tree, options?)

Render a pre-parsed ComarkTree to an ANSI-styled string.

import { renderANSI } from '@comark/ansi'

const output = await renderANSI(tree)
process.stdout.write(output)

log(markdown, options?)

Parse and render markdown directly to stdout.

import { log } from '@comark/ansi'

await log('# Hello\n\nThis is **bold**.')

Framework Renderers

@comark/vue · @comark/react · @comark/svelte · @comark/angular · @comark/nuxt: same API, different import path.

<Comark>

Parses and renders markdown in one async step.

<Comark :plugins="[highlight()]" :components="{ alert: Alert }">
  {{ content }}
</Comark>

<ComarkRenderer>

Renders a pre-parsed ComarkTree with no parser shipped to the client.

<ComarkRenderer :tree="tree" :components="{ alert: Alert }" />

defineComarkComponent(options)

Creates a pre-configured <Comark> with baked-in plugins and component mappings.

import { defineComarkComponent } from '@comark/vue' // or @comark/react, @comark/svelte, @comark/angular

export const AppComark = defineComarkComponent({
  plugins: [highlight(), toc()],
  components: { alert: CustomAlert },
})

Types

ComarkTree

interface ComarkTree {
  nodes: ComarkNode[]
  frontmatter: Record<string, any>
  meta: {
    toc?: TOC
    summary?: ComarkNode[]
    [key: string]: any
  }
}

RenderMarkdownOptions

interface RenderMarkdownOptions {
  maxInlineAttributes?: number             // Max inline attributes before switching to YAML block (default: 3)
  blockAttributesStyle?: 'frontmatter' | 'codeblock'  // Block attribute syntax style (default: 'codeblock')
  frontmatterOptions?: DumpOptions         // js-yaml options for frontmatter serialization
  components?: Record<string, NodeHandler> // Custom render handlers for specific elements
  data?: Record<string, any>              // Additional data passed to render handlers
}

ComarkNode

type ComarkNode =
  | string
  | [tag: string, props?: Record<string, any>, ...children: ComarkNode[]]

ParseOptions

interface ParseOptions {
  autoUnwrap?: boolean     // default: true
  autoClose?: boolean      // default: true
  html?: boolean           // default: true
  linkify?: boolean        // default: true
  headingIds?: boolean     // default: true
  plugins?: ComarkPlugin[]
}

TOC

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

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

Imports

imports.ts
// Core
import { parse, createParse, autoCloseMarkdown } from 'comark'
import { renderMarkdown } from 'comark/render'
import type { RenderMarkdownOptions } from 'comark/render'
import { defineComarkPlugin } from 'comark/parse'

// Plugins
import highlight from 'comark/plugins/highlight'
import emoji from 'comark/plugins/emoji'
import toc from 'comark/plugins/toc'
import summary from 'comark/plugins/summary'
import security from 'comark/plugins/security'

// HTML rendering
import { render, createRender, renderHTML } from '@comark/html'

// ANSI rendering
import { render, createRender, renderANSI, log, createLog } from '@comark/ansi'

// Vue
import { Comark, ComarkRenderer, defineComarkComponent } from '@comark/vue'

// React
import { Comark, ComarkRenderer, defineComarkComponent } from '@comark/react'

// Svelte
import { Comark, ComarkRenderer } from '@comark/svelte'

// Types
import type { ComarkTree, ComarkNode, ParseOptions, ComarkPlugin } from 'comark'
Using Nuxt? Comark and ComarkRenderer are auto-imported, no import statements needed.

Related

Streaming API

Render incomplete Markdown correctly during streaming. autoCloseMarkdown() closes unterminated syntax so AI output displays at every frame.

Comark vs MDX

Comark parses component syntax at runtime with no build step, while MDX compiles Markdown to JSX at build time. Compare syntax, architecture, framework support, and streaming.