API Reference

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

Core Parser (`comark`)

Functions

`parse(source, options?)`

Synchronous parsing of Comark content.

parse.ts

import { parse } from 'comark'

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

// Returns: ComarkTree
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)

`parse(source, options?)` with Plugins

Asynchronous parsing with plugins (e.g., syntax highlighting).

parse.ts

import { parse } from 'comark'
import highlight from 'comark/plugins/highlight'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import typescript from '@shikijs/langs/typescript'
import vue from '@shikijs/langs/vue'

const result = await parse(markdownContent, {
  plugins: [
    highlight({
      themes: { light: githubLight, dark: githubDark },
      languages: [typescript, vue]
    })
  ]
})

`createParse(options?)`

Creates a reusable parser function with pre-configured options. This is more efficient than calling parse() repeatedly when you need to parse multiple documents with the same configuration.

parse.ts

import { createParse } from 'comark'
import highlight from 'comark/plugins/highlight'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'

// Create a parser with specific options
const parse = createParse({
  autoUnwrap: true,
  plugins: [
    highlight({
      themes: { light: githubLight, dark: githubDark }
    })
  ]
})

// Reuse the parse for multiple documents
const tree1 = await parse('# Document 1\n\nContent...')
const tree2 = await parse('# Document 2\n\nMore content...')
const tree3 = await parse('# Document 3\n\nEven more...')

Benefits:

Performance: Parser and plugins are initialized once, not on every parse
Consistency: All documents parsed with the same configuration
Reusability: Perfect for batch processing or server-side rendering

Use cases:

Static site generators processing multiple markdown files
API servers parsing user-submitted content
Build tools that transform many documents
Any scenario where you parse more than one document

String Rendering (`comark/string`)

Functions

`renderHTML(tree, options?)`

Convert Comark AST to HTML string, with optional custom component renderers.

render.ts

import { renderHTML } from 'comark/string'

// Simple usage
const html = renderHTML(tree)

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

`renderMarkdown(tree)`

Convert Comark AST back to markdown.

render.ts

import { renderMarkdown } from 'comark/string'

const markdown = renderMarkdown(tree)
// "# Hello\n\nWorld"

`autoCloseMarkdown(source)`

Auto-close incomplete markdown/Comark.

auto-close.ts

import { autoCloseMarkdown } from 'comark'

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

Types

`ComarkTree`

The main return type for all parse functions.

interface ComarkTree {
  nodes: ComarkNode[]           // Parsed AST nodes
  frontmatter: Record<string, any>  // Frontmatter data
  meta: {
    toc?: any                   // Table of contents (from toc plugin)
    summary?: ComarkNode[]      // Summary content (from summary plugin)
    [key: string]: any          // Other plugin metadata
  }
}

`ParseOptions`

interface ParseOptions {
  autoUnwrap?: boolean           // Remove unnecessary <p> wrappers (default: true)
  autoClose?: boolean            // Auto-close incomplete syntax (default: true)
  html?: boolean                 // Parse embedded HTML tags into AST nodes (default: true)
  plugins?: ComarkPlugin[]       // Array of plugins to apply
}

`HighlightOptions`

Options for the highlight plugin (comark/plugins/highlight):

import type { BundledLanguage, BundledTheme } from 'shiki'

interface HighlightOptions {
  // Register common languages: vue, typescript, javascript, mdc, tsx, bash, json, yaml
  registerDefaultLanguages?: boolean

  // Register Material themes: material-theme-lighter (light), material-theme-palenight (dark)
  registerDefaultThemes?: boolean

  // Theme configuration - import from @shikijs/themes
  themes?: Record<string, BundledTheme>

  // Languages to include - import from @shikijs/langs
  languages?: BundledLanguage[]

  // Add background/foreground styles to <pre> elements
  preStyles?: boolean
}

Defaults:

registerDefaultLanguages: true (registers: vue, typescript, javascript, mdc, tsx, bash, json, yaml)
registerDefaultThemes: true (registers: material-theme-lighter, material-theme-palenight)
themes: { light: materialThemeLighter, dark: materialThemePalenight }
languages: undefined (only defaults registered)
preStyles: false

`RenderHTMLOptions`

interface RenderHTMLOptions {
  components?: Record<string, ComponentRenderFn>
  data?: Record<string, any>
}

`ComponentRenderFn`

type ComponentRenderFn = (
  element: ComarkElement,
  ctx: RenderHTMLContext
) => string

`RenderHTMLContext`

interface RenderHTMLContext {
  render: (children: ComarkNode[]) => string
  data?: Record<string, any>
}

`ComarkNode`

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

`TOC`

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

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

Quick Import Reference

imports.ts

// Core parsing
import { parse, createParse, autoCloseMarkdown } from 'comark'

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

// String rendering (HTML & Markdown)
import { renderHTML, renderMarkdown } from 'comark/string'
import type { RenderHTMLOptions, ComponentRenderFn, RenderHTMLContext } from 'comark/string'

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

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

// Types
import type {
  ComarkTree,
  ComarkNode,
  ParseOptions,
  ComarkPlugin
} from 'comark'