Cheat Sheet

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

comark (Core)

parseMarkdown(source, options?)

Parse Comark content into a MarkdownDocument.

import { parseMarkdown } from 'comark'
import shiki from 'comark/plugins/shiki'

const result = await parseMarkdown(source, {
  autoUnwrap: true,   // Remove <p> wrappers from single-paragraph containers
  autoClose: true,    // Auto-close incomplete syntax
  plugins: [shiki()]  // HTML parsing is on by default via the html plugin
})

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

createMarkdownParser(options?)

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

import { createMarkdownParser } from 'comark'

const parse = createMarkdownParser({ plugins: [shiki()] })

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

renderMarkdown(document, options?)

Convert a MarkdownDocument back to a markdown string.

import { parseMarkdown } from 'comark'
import { renderMarkdown } from 'comark/render'

const document = await parseMarkdown(source)
const markdown = await renderMarkdown(document, {
  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

renderHtml(markdown, options?)

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

import { renderHtml } from '@comark/html'

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

createHtmlRenderer(options?)

Creates a reusable parse+render function initialized once.

import { createHtmlRenderer } from '@comark/html'

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

const html = await renderHtml(source)

renderHtmlFromDocument(document, options?)

Render a pre-parsed MarkdownDocument to an HTML string.

import { renderHtmlFromDocument } from '@comark/html'

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

@comark/ansi

renderAnsi(markdown, options?)

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

import { renderAnsi } from '@comark/ansi'

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

createAnsiRenderer(options?)

Create a reusable parse-and-render function with pre-configured parser and ANSI renderer options.

import { createAnsiRenderer } from '@comark/ansi'

const renderAnsi = createAnsiRenderer({ colors: false, width: 120 })
const output = await renderAnsi('# Hello')

renderAnsiFromDocument(document, options?)

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

import { parseMarkdown } from 'comark'
import { renderAnsiFromDocument } from '@comark/ansi'

const document = await parseMarkdown('# Hello')
const output = await renderAnsiFromDocument(document)
process.stdout.write(output)

writeAnsi(markdown, options?)

Parse and render markdown directly to stdout.

import { writeAnsi } from '@comark/ansi'

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

createAnsiWriter(options?)

Create a reusable Markdown writer. Pass writer to target something other than process.stdout.

import { createAnsiWriter } from '@comark/ansi'

const writeAnsi = createAnsiWriter({
  writer: (output) => process.stderr.write(output),
})

await writeAnsi('# Hello')

Framework Renderers

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

<Markdown>

Parses and renders markdown in one async step.

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

<MarkdownDocument>

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

<MarkdownDocument :value="document" :components="{ alert: Alert }" />

defineMarkdownComponent(options)

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

import { defineMarkdownComponent } // or @comark/react, @comark/svelte, @comark/angular

export const AppMarkdown = defineMarkdownComponent({
  plugins: [shiki(), toc()],
  components: { alert: CustomAlert },
})

Types

MarkdownDocument

interface MarkdownDocument {
  nodes: Node[]
  frontmatter: Record<string, any>
  meta: {
    toc?: TOC
    summary?: Node[]
    [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
}

Node

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

ParserOptions

interface ParserOptions {
  autoUnwrap?: boolean              // default: true
  autoClose?: boolean               // default: true
  /** @deprecated Prefer registerDefaultPlugins: false */
  html?: boolean                    // default: true
  linkify?: boolean                 // default: true
  headingIds?: boolean              // default: true
  registerDefaultPlugins?: 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 { parseMarkdown, createMarkdownParser, autoCloseMarkdown } from 'comark'
import { renderMarkdown } from 'comark/render'
import type { RenderMarkdownOptions } from 'comark/render'
import { defineComarkPlugin } from 'comark'

// Plugins
import shiki from 'comark/plugins/shiki'
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 { createHtmlRenderer, renderHtml, renderHtmlFromDocument } from '@comark/html'

// ANSI rendering
import {
  renderAnsi,
  renderAnsiFromDocument,
  createAnsiRenderer,
  writeAnsi,
  createAnsiWriter,
} from '@comark/ansi'

// Vue
import { Markdown, MarkdownDocument, defineMarkdownComponent } from '@comark/vue'

// React
import { Markdown, MarkdownDocument, defineMarkdownComponent } from '@comark/react'

// Svelte
import { Markdown, MarkdownDocument } from '@comark/svelte'

// Types
import type {
  MarkdownDocument,
  ElementNode,
  TextNode,
  CommentNode,
  ElementNodeAttributes,
  Node,
  ParserOptions,
  ComarkPlugin,
} from 'comark'
Using Nuxt? Markdown and MarkdownDocument 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.