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/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

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
  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

Handle incomplete or partial Comark content with utilities for streaming scenarios where content arrives incrementally.

Why Comark?

Markdown is human-readable, token-efficient, and AI-native. Comark extends it to interactive components with runtime parsing, multi-framework rendering, and first-class streaming.