Parse API

Parse Markdown into a compact, serializable document with parseMarkdown() or createMarkdownParser(), on the server, in the browser, or from a stream.

parseMarkdown(source, options?)

Parses Markdown from a string and returns a complete MarkdownDocument. Default plugins add frontmatter, alerts, task lists, HTML, components, and attributes to the standard Markdown parser.

Parameters:

  • source - The Markdown content as a string
  • options? - Parser options including plugins

Returns: MarkdownDocument object containing:

  • nodes - The parsed Markdown AST nodes
  • frontmatter - Frontmatter data parsed from YAML
  • meta - Additional metadata from plugins (for example, toc, summary)

Example:

import { parseMarkdown } from 'comark'

const content = `---
title: Hello World
---

This is an example
`

const result = await parseMarkdown(content)

console.log(result)
For the complete parsed document and node types, see the Document model.

Frontmatter

parseMarkdown() extracts and parses YAML frontmatter by default:

const content = `---
title: My Document
tags:
  - javascript
  - markdown
author:
  name: John Doe
  email: john@example.com
---

# Content here
`

const result = await parseMarkdown(content)
console.log(result.frontmatter)

Table of contents

Register the toc plugin to generate a table of contents based on headings:

import toc from 'comark/plugins/toc'

const content = `# Main Title

## Section 1

Some content here.

### Subsection 1.1

More content.

## Section 2

Final content.
`

const result = await parseMarkdown(content, { plugins: [toc()] })
console.log(result.meta.toc)

HTML parsing

HTML tags embedded in Comark content are parsed into AST nodes by default and can be mixed freely with Comark components and Markdown syntax.

const content = `
<div class="note">
  ::alert{type="info"}
  Hello <strong class="text-red-500">world</strong>
  ::
</div>
`

const result = await parseMarkdown(content)
console.log(result.nodes)

HTML parsing is provided by the built-in html plugin.

Summary

Summary extraction requires the summary plugin.

With the summary plugin, Comark extracts content before <!-- more --> into result.meta.summary:

parse.ts
import { parseMarkdown } from 'comark'
import summary from 'comark/plugins/summary'

const content = `# Article Title

This is the introduction paragraph that will be used as a summary.

<!-- more -->

This is the full article content that won't appear in the summary.
`

const result = await parseMarkdown(content, {
  plugins: [summary()]
})

console.log(result.meta.summary)
// Node[] with only the content before <!-- more -->

createMarkdownParser(options?)

Creates a reusable parser function with pre-configured options. parseMarkdown() initializes a new parser on each call; createMarkdownParser() initializes the parser and its plugins once and reuses them across calls.

Parameters:

  • options? - Parser options (same as parseMarkdown())

Returns: An async parser function (source: string) => Promise<MarkdownDocument>

Example:

parse.ts
import { createMarkdownParser } from 'comark'
import shiki from 'comark/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import emoji from 'comark/plugins/emoji'
import toc from 'comark/plugins/toc'

const parse = createMarkdownParser({
  autoUnwrap: true,
  autoClose: true,
  plugins: [
    shiki({
      themes: { light: githubLight, dark: githubDark }
    }),
    emoji(),
    toc()
  ]
})

const doc1 = await parse('# Document 1\n\nContent...')
const doc2 = await parse('# Document 2\n\nMore content...')
const doc3 = await parse('# Document 3\n\nEven more...')

Use cases

Static site generator

Use Promise.all to parse all files in parallel. Since createMarkdownParser() initializes the parser once, the returned function is safe to call concurrently.

build.ts
import { createMarkdownParser } from 'comark'
import { readdir, readFile, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { renderHtmlFromDocument } from '@comark/html'
import shiki from 'comark/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import toc from 'comark/plugins/toc'
import emoji from 'comark/plugins/emoji'

async function buildSite(contentDir: string, outDir: string) {
  const parse = createMarkdownParser({
    plugins: [
      shiki({
        themes: { light: githubLight, dark: githubDark }
      }),
      toc({ depth: 3 }),
      emoji()
    ]
  })

  const files = await readdir(contentDir)
  const mdFiles = files.filter(f => f.endsWith('.md'))

  await Promise.all(
    mdFiles.map(async (file) => {
      const content = await readFile(join(contentDir, file), 'utf-8')
      const doc = await parse(content)
      const html = await renderHtmlFromDocument(doc)
      await writeFile(join(outDir, file.replace('.md', '.html')), html)
    })
  )

  console.log(`Built ${mdFiles.length} pages`)
}

await buildSite('./content', './dist')

API server

server.ts
import { createMarkdownParser } from 'comark'
import security from 'comark/plugins/security'

const parse = createMarkdownParser({
  plugins: [
    security() // Sanitize user-generated content
  ]
})

app.post('/api/markdown', async (req, res) => {
  try {
    const tree = await parse(req.body.content)
    res.json({ success: true, tree })
  } catch (error) {
    res.status(400).json({ error: 'Invalid markdown' })
  }
})

Benchmark

createMarkdownParser() initializes the parser and plugins (such as Shiki's highlighter) once instead of recreating them on every call:

benchmark.ts
import { parseMarkdown, createMarkdownParser } from 'comark'
import shiki from 'comark/plugins/shiki'

const content = '```js\nconsole.log("hello")\n```'

// Slow: recreates parser and highlighter on every call
console.time('parse x1000')
for (let i = 0; i < 1000; i++) {
  await parseMarkdown(content, {
    plugins: [shiki()]
  })
}
console.timeEnd('parse x1000')
// → ~8000ms (parser + highlighter recreated 1000 times)

// Fast: reuses one parser and highlighter instance
console.time('createMarkdownParser x1000')
const parse = createMarkdownParser({
  plugins: [shiki()]
})
for (let i = 0; i < 1000; i++) {
  await parse(content)
}
console.timeEnd('createMarkdownParser x1000')
// → ~800ms (parser + highlighter created once)

Entry points

ImportContents
comarkparseMarkdown(), createMarkdownParser(), createSerializedMarkdownParser() with the default plugins and auto-close, plus autoCloseMarkdown(), createComarkContext(), defineComarkPlugin(), parseFrontmatter()
comark/coreThe same three parser functions with no default plugins and no built-in auto-closer
comark/auto-closeautoCloseMarkdown() and its placeholders, without the parser
comark/contextcreateComarkContext() and the live-update types, without the parser
comark/parseDeprecated. Alias of comark. Import from comark instead

comark/core

Use comark/core when you want to choose every plugin yourself and keep the default plugins out of your bundle. It accepts the same options as comark, with two differences:

  • Only the plugins in plugins run. registerDefaultPlugins is not accepted; add linkify() to link bare URLs.
  • autoClose is a function or undefined (the default, which skips auto-closing). Pass autoCloseMarkdown from comark/auto-close to opt in.
core.ts
import { createMarkdownParser } from 'comark/core'
import { autoCloseMarkdown } from 'comark/auto-close'
import components from 'comark/plugins/components'

const parse = createMarkdownParser({
  plugins: [components()],
  autoClose: (markdown, streaming) => autoCloseMarkdown(markdown, { dropTrailingOpeners: streaming }),
})

const tree = await parse('::alert\n**Streaming')

Options

Both parseMarkdown() and createMarkdownParser() accept the same ParserOptions:

OptionTypeDefaultDescription
autoUnwrapbooleantrueRemove unnecessary <p> wrappers from single-element containers. Each component slot (the default content and every #name slot) is unwrapped on its own.
autoCloseboolean | (markdown: string, streaming?: boolean) => stringtrueAuto-close incomplete Markdown syntax, or use a custom completion function. streaming is true when the parse was called with { streaming: true }.
unwrapboolean | string | string[]falseRemove wrapper tags from the tree and hoist their children (MDC unwrap behavior). true unwraps p; a comma- or whitespace-separated string or array unwraps the listed tags; '*' matches any tag. Tags apply sequentially (each descends one level), and adjacent text is merged into a single string.
linkifybooleantrueDeprecated. Use registerDefaultPlugins: false and register linkify() only when needed. Still honored (over registerDefaultPlugins) and logs a warning
headingIdsboolean | 'nested' | 'flat'trueAuto-generate id attributes for h1 through h6 from visible heading text (not tag or component names). true/'flat' uses the heading's own text only (install); 'nested' prefixes each id with its parent heading's id (setup-install); false disables auto ids. Unicode letters, marks, and numbers are kept (## Café → café); punctuation and symbols are dropped, and a heading that slugifies to nothing gets no id. Ids are unique per document, and duplicates get a -1, -2, ... suffix (options, options-1, options-2). An explicit id attribute wins. See Headings.
registerDefaultPluginsbooleantrueRegister the built-in default plugins (linkify, frontmatter, html, alert, task-list, components, attributes). Set false to disable them.
pluginsComarkPlugin[][]Ordered plugins to run after the defaults. A same-name plugin replaces its default; duplicate explicit names keep the first instance. See Default plugins.
tracerComarkTracerundefinedTiming recorder for the parse pipeline. See Timing the parse

Timing the parse

Pass a tracer to time each phase of the pipeline and every plugin hook, such as a slow post Shiki hook. ComarkTracer uses startSpan and startActiveSpan, a structural subset of the OpenTelemetry Tracer interface, so an OpenTelemetry tracer works as-is:

import { trace } from '@opentelemetry/api'
import shiki from 'comark/plugins/shiki'

const parse = createMarkdownParser({
  // Uses the OpenTelemetry provider registered by your app or hosting platform.
  tracer: trace.getTracer('comark'),
  plugins: [shiki()],
})
@opentelemetry/api defines the tracing API but does not export spans by itself. trace.getTracer() uses the globally registered OpenTelemetry provider; without one, it returns a no-op tracer. Hosting platforms often register and configure that provider for you. Otherwise, initialize an OpenTelemetry SDK and exporter before creating the parser.

See the complete Node.js example, including an OTLP/HTTP exporter and commands for viewing traces locally with otel-front.

You can also pass a custom recorder:

const spans: { name: string, duration: number }[] = []
const tracer = {
  startSpan(name) {
    const start = performance.now()
    return { end: () => spans.push({ name, duration: performance.now() - start }) }
  },
  startActiveSpan(name, optionsOrFn, maybeFn) {
    const fn = typeof optionsOrFn === 'function' ? optionsOrFn : maybeFn
    const span = tracer.startSpan(name)
    // Nested startActiveSpan/startSpan calls become children via your context/stack.
    return fn(span) // caller (comark) ends the span
  },
}

const parse = createMarkdownParser({ tracer, plugins: [shiki()] })
await parse(markdown)
// spans → comark:parse
//           ├─ comark:autoclose
//           ├─ comark:pre:frontmatter
//           ├─ comark:tokenize
//           ├─ comark:nodes
//           ├─ comark:post:alert
//           └─ comark:post:shiki
//           ...

Comark records a root comark:parse active span containing comark:autoclose, comark:tokenize (Markdown parsing), comark:nodes (token-to-AST conversion and unwrapping), and comark:pre:<name> / comark:post:<name> for each plugin hook. Nested startActiveSpan calls form the parent-to-child hierarchy via the OpenTelemetry active context or a stack in a custom recorder. Omitting tracer adds no timing overhead, and tracing uses no Node-specific APIs, so it works in the browser too.

Inline rendering

Use unwrap: 'p' (or unwrap: true) to render Markdown without the wrapping <p>, for example inside buttons, badges, and other inline elements. Comark merges adjacent text into a single string, matching MDC's unwrap:

await parseMarkdown('Hello **world**', { unwrap: 'p' })
// nodes: ['Hello ', ['strong', {}, 'world']]

await parseMarkdown('a\n\nb', { unwrap: true })
// nodes: ['ab']   (paragraphs merged, no separator)

Comark applies tags sequentially, descending one level for each tag, so a space- or comma-separated list peels nested wrappers. '*' matches any tag:

// Unwrap the <ul>, then the <li> inside it
await parseMarkdown('- Buy milk', { unwrap: 'ul li' })
// nodes: ['Buy milk']

On the framework components this is exposed as an unwrap shorthand prop:

<UButton><Markdown :value="text" unwrap /></UButton>
<UButton><Markdown :value="text" unwrap="ul li" /></UButton>
<UButton><Markdown :value="text" :options="{ unwrap: 'p' }" /></UButton>

© 2026 Vercel, Inc.