Plugins

Extend Comark with plugins for syntax highlighting, emoji, table of contents, math, and diagrams, or reuse existing markdown-it plugins.

Comark has two compatible extension layers. Comark plugins can transform source, tokens, the parsed document, or rendered output through typed lifecycle hooks. You can also reuse parser plugins written for markdown-it through Comark's markdown-exit foundation.

All Comark plugins are part of the core comark package, while optional rendering dependencies are installed only when you use them.

Default plugins

These plugins are enabled by default whenever you call parseMarkdown() or createMarkdownParser() (or a framework <Markdown> component). You do not need to install or register them.

Frontmatter

Parse a leading YAML frontmatter block into tree.frontmatter

HTML

Parse embedded HTML tags into Comark AST nodes

Alerts

Transform GitHub-style > [!NOTE] blockquotes

Task List

Interactive [ ] / [x] checkboxes

Components

Block/inline components and spans (::name, :name, [text])

Attributes

Inline attributes ({props} after tokens)
Default plugins run in the order shown above. Plugins you pass through plugins run afterward in the order you provide them. If an explicit plugin has the same name as a default plugin, it replaces that default and runs in its explicit position. If you provide the same explicit plugin name more than once, only the first instance runs.

Disable default plugins

Turn them all off with registerDefaultPlugins: false:

import { parseMarkdown } from 'comark'

// Plain markdown only — no components, attributes, HTML, alerts, or task lists
const result = await parseMarkdown(content, {
  registerDefaultPlugins: false,
})

Opt back into specific defaults via plugins:

import { parseMarkdown } from 'comark'
import components from 'comark/plugins/components'
import attributes from 'comark/plugins/attributes'

const result = await parseMarkdown(content, {
  registerDefaultPlugins: false,
  plugins: [components(), attributes()],
})

See the registerDefaultPlugins and plugins options on the Parse API.

Plugins

Optional plugins you register via plugins: [...].

Binding

Interpolate frontmatter, runtime data, or parent props with {{ path || default }} shorthand

Breaks

Convert soft line breaks directly into :br components

Emoji

Convert emoji shortcodes like :smile: into emoji characters

Footnotes

Plugin for adding footnote references and definitions to your Comark documents.

Headings

Plugin for extracting the page title and description from document content.

JSON Render

Transform JSON Render specs into UI components using json-render or yaml-render code blocks

Mathematics

Render LaTeX math formulas using KaTeX with inline and display equations

Mermaid Diagrams

Create diagrams and visualizations using Mermaid syntax in code blocks

Punctuation

Convert plain-text punctuation into typographically correct Unicode characters

Security

Sanitize markdown by removing dangerous HTML elements and attributes

Summary Extraction

Extract content summaries using <!-- more --> delimiter

Shiki

Beautiful code syntax highlighting using Shiki with multi-theme support

Rangi

Lightweight highlighting via rangi (~13kB all-in, dual themes)

Table of Contents

Generate hierarchical TOC from headings automatically

Guides

Plugin API

Define plugins with the ComarkPlugin interface and lifecycle hooks

AST API

Traverse and transform the MarkdownDocument AST using the visit() utility

Markdown-it Plugins

Use existing markdown-it plugins or create new parser syntax rules

Use plugins

Pass plugins to parseMarkdown() or the <Markdown> component:

import { parseMarkdown } from 'comark'
import emoji from 'comark/plugins/emoji'
import toc from 'comark/plugins/toc'

const result = await parseMarkdown(content, {
  plugins: [
    emoji(),
    toc({ depth: 3 })
  ]
})