---
title: "Cheat Sheet"
description: "Quick reference for all Comark exports, types, and APIs across all packages."
canonical_url: "https://comark.dev/reference/reference"
---
# 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`.

```typescript
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.

```typescript
import { createMarkdownParser } from 'comark'

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

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

### `renderMarkdown(document, options?)`

Convert a `MarkdownDocument` back to a markdown string.

```typescript
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.

```typescript
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.

```typescript
import { renderHtml } from '@comark/html'

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

#### `createHtmlRenderer(options?)`

Creates a reusable parse+render function initialized once.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

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

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

#### `printAnsi(markdown, options?)`

Parse and render markdown directly to stdout. Replaces the deprecated `writeAnsi` alias.

```typescript
import { printAnsi } from '@comark/ansi'

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

#### `createAnsiPrinter(options?)`

Create a reusable Markdown printer. Pass `writer` to target something other than `process.stdout`. Replaces the deprecated `createAnsiWriter` alias.

```typescript
import { createAnsiPrinter } from '@comark/ansi'

const printAnsi = createAnsiPrinter({
  writer: (output) => process.stderr.write(output),
})

await printAnsi('# 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.

::code-group
```vue [Vue]
<Markdown :plugins="[shiki()]" :components="{ alert: Alert }">
  {{ content }}
</Markdown>
```

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

```svelte [Svelte]
<Markdown value={content} plugins={[shiki()]} components={{ alert: Alert }} />
```

```html [Angular]
<comark-markdown [value]="content" [plugins]="[shiki()]" [components]="{ alert: Alert }" />
```
::

### `<MarkdownDocument>`

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

::code-group
```vue [Vue]
<MarkdownDocument :value="document" :components="{ alert: Alert }" />
```

```tsx [React]
<MarkdownDocument value={document} components={{ alert: Alert }} />
```

```svelte [Svelte]
<MarkdownDocument value={document} components={{ alert: Alert }} />
```

```html [Angular]
<comark-markdown-document [value]="document" [components]="{ alert: Alert }" />
```
::

### `defineMarkdownComponent(options)`

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

```typescript
import { defineMarkdownComponent } from '@comark/vue' // or @comark/react, @comark/angular

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

## Transforming nodes before render

`transformNode` lets you change the tag or props of an element node right before it renders, based on its props and the render context. Use it when a value is only known at render time, such as runtime `data`, and `components` alone can't express the change.

The option takes a function or an array of functions. Every renderer accepts it: the `<Markdown>` and `<MarkdownDocument>` components in Vue, React, Svelte, and Angular, `defineMarkdownComponent`, `defineMarkdownDocumentComponent`, and the `@comark/html` and `@comark/ansi` render functions.

```typescript
import type { NodeTransform } from 'comark'

// Render every `::cta` as a link to the signed-in user's dashboard
const transformNode: NodeTransform = ({ tag, props, renderData }) => {
  if (tag !== 'cta') return
  return {
    tag: 'a',
    props: { ...props, href: `/users/${renderData.data.userId}/dashboard` },
  }
}
```

::code-group
```vue [Vue]
<MarkdownDocument :value="document" :data="{ userId: 42 }" :transform-node="transformNode" />
```

```tsx [React]
<MarkdownDocument value={document} data={{ userId: 42 }} transformNode={transformNode} />
```

```svelte [Svelte]
<MarkdownDocument value={document} data={{ userId: 42 }} {transformNode} />
```

```html [Angular]
<comark-markdown-document [value]="document" [data]="{ userId: 42 }" [transformNode]="transformNode" />
```

```typescript [HTML]
const html = await renderHtmlFromDocument(document, { data: { userId: 42 }, transformNode })
```
::

The function receives:

- `tag`: the tag the renderer will use.
- `props`: the node's attributes with `:` bindings resolved. Every renderer resolves them the same way: the `:` is removed, the value is parsed as JSON, and a value that isn't JSON is looked up as a data path. `:count="5"` gives `{ count: 5 }`, and a path that doesn't exist gives `undefined`.
- `node`: the node as it is in the document.
- `parent`: the parent element node, when the renderer knows it. Svelte doesn't pass it.
- `renderData`: `{ frontmatter, meta, data, props }`, where `props` holds the parent's props.

Return `{ tag?, props? }` to replace either one, or nothing to keep the node as it is. The returned props are final: `:` keys in them aren't resolved again. The node's children then see the returned props as their parent props, so `:title="props.title"` in a child reads the new value.

These rules apply:

- **Lookup:** a returned tag is looked up like any tag, in `components`, then `componentsManifest`, then as a native element. An `as` prop still takes precedence in Vue, React, and Angular, so remove it from `props` if the new tag must win.
- **Order:** with an array, each function sees the result of the previous one. `defineMarkdownComponent` and `defineMarkdownDocumentComponent` run their own `transformNode` before the instance's.
- **Safety:** the returned tag and props are rendered as-is, like the output of a custom component. Comark doesn't sanitize them, and the [security plugin](https://comark.dev/plugins/built-in/security) runs at parse time, so its options don't apply either. You're responsible for validating anything the function builds from untrusted data, such as URLs from `data`, and for returning a valid tag name.
- **Purity:** the function must be synchronous and must not mutate `props`, `node`, or `renderData`. It runs for every element node on every render, and Angular can call it twice for a node that renders as a custom component.
- **Stable reference:** in Vue, React, and Angular, define the function or array once, outside the render. A new array on every render makes the document render again.

---

## Types

### `MarkdownDocument`

```typescript
interface MarkdownDocument {
  nodes: Node[]
  frontmatter: Record<string, any>
  meta: {
    toc?: Toc
    summary?: Node[]
    [key: string]: any
  }
}
```

### `RenderMarkdownOptions`

```typescript
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 | ConditionalNodeHandler> // Custom render handlers for specific elements
  data?: Record<string, any>              // Additional data passed to render handlers
}
```

### `Node`

```typescript
type Node =
  | string                                                        // TextNode
  | [tag: string, attrs: ElementNodeAttributes, ...children: Node[]]  // ElementNode
  | [tag: null, attrs: ElementNodeAttributes, comment: string]        // CommentNode
```

### `ParserOptions`

```typescript
interface ParserOptions {
  autoUnwrap?: boolean              // default: true
  autoClose?: boolean | AutoCloseFunction // default: true
  unwrap?: boolean | string | string[]  // strip top-level wrapper tags, e.g. 'p' (default: false)

  linkify?: boolean                 // deprecated: use registerDefaultPlugins: false + linkify()
  headingIds?: boolean | 'nested' | 'flat' // default: true ('flat') — slug from visible text; duplicates get -1, -2, … (keeps Unicode letters/numbers, omits symbol-only ids); explicit id wins
  registerDefaultPlugins?: boolean  // default: true
  plugins?: ComarkPlugin[]
  tracer?: ComarkTracer             // OpenTelemetry-style tracer for parse spans
}
```

### `Toc`

```typescript
// Exported from 'comark/plugins/toc'
interface Toc {
  title: string
  depth: number
  searchDepth: number
  links: TocLink[]
}

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

---

## Imports

```typescript [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,
  printAnsi,
  createAnsiPrinter,
} 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'
```

::tip{to="https://comark.dev/rendering/nuxt"}
Using Nuxt? `Markdown` and `MarkdownDocument` are auto-imported, no import statements needed.
::

---

## Related

- [Parse API](https://comark.dev/reference/parse) - Full parse options, plugins, and examples
- [Render API](https://comark.dev/reference/render) - Render a `MarkdownDocument` back to markdown
- [Streaming API](https://comark.dev/reference/auto-close) - Handle incomplete syntax for streaming
- [HTML Rendering](https://comark.dev/rendering/html) - Server-side HTML generation
- [Vue Rendering](https://comark.dev/rendering/vue) - Render in Vue applications
- [React Rendering](https://comark.dev/rendering/react) - Render in React applications
- [Svelte Rendering](https://comark.dev/rendering/svelte) - Render in Svelte applications
- [Nuxt Rendering](https://comark.dev/rendering/nuxt) - Zero-config Nuxt module
- [ANSI Rendering](https://comark.dev/rendering/ansi) - Terminal output
- [Plugins](https://comark.dev/plugins) - Syntax highlighting, math, TOC, and more
- [Document Model](https://comark.dev/getting-started/document-model) - Parsed document and node model

---

- [Parse API](https://comark.dev/reference/parse)
- [Render API](https://comark.dev/reference/render)


## Sitemap

See the full [sitemap](https://comark.dev/sitemap.md) for all pages.
