Migrating from MDC
Comark replaces @nuxtjs/mdc. The Markdown and component syntax stays the same, so most .md files need no edits. This guide covers the JavaScript API changes, including package names, parse functions, the tuple AST, and plugins.
Quick overview
- Package:
@nuxtjs/mdc→comark(core) or@comark/vue(Vue renderer and Nuxt module) - Parse:
parseMarkdown(), and synchronouscreateMarkdownParser()(noawait) - AST: object tree → compact tuples
['tag', props, ...children] - Result:
result.bodyandresult.data→document.nodesanddocument.frontmatter - Renderer:
<MDCRenderer :body :data>→<MarkdownDocument :value> - All-in-one:
<MDC :value>→<Markdown :value> - Slots:
<MDCSlot />→ native<slot /> - Plugins: global
nuxt.config→ per-componentdefineMarkdownComponent({ plugins }) - Binding:
{{ path }}via opt-in binding plugin and render-timedataprop (namespaced paths) - Markdown files: component syntax unchanged; update binding paths if you used bare MDC names
Agent skill
Install the migration skill to let coding agents update a project from MDC to Comark:
npx skills add https://comark.dev/skills/migrate-mdc-to-comarkPackage changes
If you only use the programmatic API (parse functions, plugins, AST utilities), install comark:
npm uninstall @nuxtjs/mdc
npm install comarkpnpm remove @nuxtjs/mdc
pnpm add comarkyarn remove @nuxtjs/mdc
yarn add comarkbun remove @nuxtjs/mdc
bun add comarkIf you also use Vue components or the Nuxt module, install @comark/vue instead. It includes comark as a dependency:
npm uninstall @nuxtjs/mdc
npm install @comark/vuepnpm remove @nuxtjs/mdc
pnpm add @comark/vueyarn remove @nuxtjs/mdc
yarn add @comark/vuebun remove @nuxtjs/mdc
bun add @comark/vueCore package
Every renderer builds on comark. These API changes apply whenever you call the parser in code, with or without Nuxt.
Parse functions
One-shot parsing
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
const result = await parseMarkdown(markdown)import { parseMarkdown } from 'comark'
const document = await parseMarkdown(markdown)Reusable parser
import { createMarkdownParser } from '@nuxtjs/mdc/runtime'
const parser = await createMarkdownParser(options)
const result = await parser(markdown)import { createMarkdownParser } from 'comark'
const parse = createMarkdownParser(options) // synchronous, no await
const document = await parse(markdown)createMarkdownParser() is synchronous and returns the parser right away. MDC's factory was async because it initialized a unified pipeline.
Render functions
Serialize back to Markdown
import { stringifyMarkdown } from '@nuxtjs/mdc/runtime'
const markdown = stringifyMarkdown(result.body, result.data)import { renderMarkdown } from 'comark/render'
const markdown = await renderMarkdown(document)renderMarkdown() reads document.frontmatter and writes it as YAML frontmatter. See the Render API for options.
Return type
The parsed document uses new field names:
// MDCParserResult
{
body: MDCRoot // the AST
data: { // frontmatter
title: string
description: string
[key: string]: any
}
toc: Toc | undefined
excerpt: MDCRoot | undefined
}// MarkdownDocument
{
nodes: Node[] // the AST
frontmatter: Record<string, any> // frontmatter (all keys)
meta: {
toc?: Toc // requires toc plugin
summary?: Node[] // requires summary plugin
[key: string]: any
}
}| MDC | Comark |
|---|---|
result.body | document.nodes |
result.data | document.frontmatter |
result.data.title | document.frontmatter.title |
result.toc | document.meta.toc (requires toc plugin) |
result.excerpt | document.meta.summary (requires summary plugin) |
AST format
MDC represents nodes as objects. Comark represents elements as tuples and text as plain strings:
// MDC object tree
{
type: 'element',
tag: 'p',
props: { class: 'intro' },
children: [
{ type: 'text', value: 'Hello world' }
]
}// Comark tuple array
['p', { class: 'intro' }, 'Hello world']
// tag attributes children...Node checks and property access map as follows:
| MDC | Comark |
|---|---|
node.type === 'element' | Array.isArray(node) |
node.type === 'text' | typeof node === 'string' |
node.tag | node[0] |
node.props | node[1] |
node.children | node.slice(2) |
Update custom AST walkers to use tuple indexing, or traverse documents with visit() from comark/utils.
Plugins
MDC ran remark and rehype plugins on unified. Comark uses its own plugin interface and supports markdown-it parsing rules.
Syntax highlighting
import { createMarkdownParser, rehypeHighlight, createShikiHighlighter } from '@nuxtjs/mdc/runtime'
const parser = await createMarkdownParser({
rehype: {
plugins: {
highlight: {
instance: rehypeHighlight,
options: {
theme: 'material-theme-palenight',
highlighter: createShikiHighlighter({ /* ... */ }),
},
},
},
},
})import { createMarkdownParser } from 'comark'
import shiki from 'comark/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
const parse = createMarkdownParser({
plugins: [
shiki({
themes: { light: githubLight, dark: githubDark }
})
]
})Table of contents
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
const result = await parseMarkdown(md, { toc: { depth: 3 } })
const toc = result.tocimport { parseMarkdown } from 'comark'
import toc from 'comark/plugins/toc'
const document = await parseMarkdown(md, { plugins: [toc({ depth: 3 })] })
const tableOfContents = document.meta.tocExcerpt and summary
const result = await parseMarkdown(md)
const excerpt = result.excerpt // MDCRoot | undefinedimport { parseMarkdown } from 'comark'
import summary from 'comark/plugins/summary'
const document = await parseMarkdown(md, { plugins: [summary()] })
const summaryNodes = document.meta.summary // Node[] | undefinedEmoji
// enabled by default via remark-emoji
// mdc: { remarkPlugins: { 'remark-emoji': {} } }import { parseMarkdown } from 'comark'
import emoji from 'comark/plugins/emoji'
const document = await parseMarkdown(md, { plugins: [emoji()] })Binding ({{ }})
MDC's built-in {{ }} syntax moves to the opt-in binding plugin. See Binding and data passing for namespaced paths and the render-time data prop.
import { parseMarkdown } from 'comark'
import binding from 'comark/plugins/binding'
const document = await parseMarkdown(md, { plugins: [binding()] })
// Pass runtime data to the renderer, not to parseMarkdown()Parse options
// MDCOptions
{
remark: { plugins: { /* record */ } },
rehype: { options: {...}, plugins: { /* record */ } },
highlight: { theme: '...', langs: [...] } | false,
toc: { depth: 3, searchDepth: 2 } | false,
keepComments: false,
keepPosition: false,
}// ParserOptions
{
plugins: ComarkPlugin[], // ordered array, not a record
autoUnwrap: true, // removes <p> from single-paragraph containers
autoClose: true, // completes unfinished syntax during streaming
// linkify, frontmatter, html, alert, task-list, components, and attributes are on by default
}The mdc.config.ts unified pipeline hooks (pre, remark, rehype, post) have no equivalent because Comark doesn't use unified. Use the ComarkPlugin interface instead.
Nuxt module
Configuration
export default defineNuxtConfig({
modules: ['@nuxtjs/mdc'],
mdc: { highlight: { ... }, remarkPlugins: { ... } },
})export default defineNuxtConfig({
modules: ['@comark/vue'],
// Configure plugins per component with defineMarkdownComponent()
})@comark/vue auto-imports Markdown, MarkdownDocument, defineMarkdownComponent, defineMarkdownDocumentComponent, parseMarkdown, and createMarkdownParser. Plugin and component configuration moves out of nuxt.config.ts and into component definitions.
Renderer component
<MDCRenderer :body="result.body" :data="result.data" :components="components" /><MarkdownDocument :value="document" :components="components" />Props that changed:
MDC <MDCRenderer> | Comark <MarkdownDocument> | Notes |
|---|---|---|
body (MDCRoot) | value (MarkdownDocument) | Takes the full MarkdownDocument (see AST format) |
data (frontmatter) | Removed | Frontmatter lives on document.frontmatter |
| Not supported | data | Runtime values for data binding and {{ }}, not frontmatter |
tag | Removed | Wrapper is <div class="comark-content"> |
prose | Removed | Prose* component resolution is automatic |
unwrap | unwrap prop or parse option | <Markdown unwrap /> or :options="{ unwrap: 'p' }". See inline rendering |
class | Removed | Style the wrapper via CSS |
components | components | Same purpose and shape |
| Not supported | componentsManifest | Async component resolver |
| Not supported | streaming | Streaming mode |
| Not supported | effects | Stream effects such as the blinking caret() from comark/stream. See stream effects |
All-in-one component
The <MDC> component maps to <Markdown>.
<MDC :value="markdown" :parser-options="options" />
<MDC :value="result" /> <!-- pre-parsed MDCParserResult --><Markdown :value="markdown" :options="options" />
<!-- or default slot -->
<Markdown>{{ markdown }}</Markdown>For a pre-parsed document, use <MarkdownDocument> instead of passing it to <Markdown>.
defineMarkdownComponent
MDC configured plugins once in nuxt.config.ts for every parse call. In Comark, defineMarkdownComponent() and defineMarkdownDocumentComponent() create named components with their own plugins and component maps.
For example, an app can use one component with syntax highlighting, a table of contents, and emoji for articles, and a plain component for user comments:
import { defineMarkdownComponent, defineMarkdownDocumentComponent } from '@comark/vue'
import shiki from '@comark/vue/plugins/shiki'
import toc from '@comark/vue/plugins/toc'
import emoji from '@comark/vue/plugins/emoji'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import CustomAlert from '~/components/Alert.vue'
import ProsePre from '~/components/ProsePre.vue'
export const ArticleMarkdown = defineMarkdownComponent({
name: 'ArticleMarkdown',
plugins: [
shiki({ themes: { light: githubLight, dark: githubDark } }),
toc({ depth: 3 }),
emoji(),
],
components: {
alert: CustomAlert,
ProsePre,
},
})
export const CommentMarkdown = defineMarkdownComponent({
name: 'CommentMarkdown',
})<script setup lang="ts">
import { ArticleMarkdown, CommentMarkdown } from '~/composables/markdown'
</script>
<template>
<ArticleMarkdown>{{ article.content }}</ArticleMarkdown>
<CommentMarkdown v-for="c in comments" :key="c.id">{{ c.body }}</CommentMarkdown>
</template>The same pattern applies to defineMarkdownDocumentComponent when you pre-parse on the server:
export const ArticleMarkdownDocument = defineMarkdownDocumentComponent({
name: 'ArticleMarkdownDocument',
components: {
alert: CustomAlert,
ProsePre,
},
})<script setup lang="ts">
import { ArticleMarkdownDocument } from '~/composables/markdown'
const { data: document } = await useFetch(`/api/article/${slug}`)
</script>
<template>
<ArticleMarkdownDocument :value="document" />
</template>Slots in custom components
MDC required a special <MDCSlot> component inside your custom Vue components to render children. Comark uses the native Vue <slot> element instead.
Default slot
<template>
<div class="alert">
<MDCSlot />
</div>
</template><template>
<div class="alert">
<slot />
</div>
</template>Unwrapping children
MDC's <MDCSlot unwrap="p"> and the older <slot mdc-unwrap="p"> attribute both map to <slot unwrap="p">:
<!-- MDCSlot -->
<MDCSlot unwrap="p" />
<!-- older mdc-unwrap attribute -->
<slot mdc-unwrap="p" /><slot unwrap="p" />The unwrap attribute strips the given wrapper tags from slot children, such as the <p> around single-paragraph slot content.
Named slots
Named slots work the same way as in MDC. Write #header in Markdown and <slot name="header" /> in the Vue component:
<!-- components/Card.vue -->
<template>
<div class="card">
<div class="card-header">
<slot name="header" />
</div>
<div class="card-body">
<slot unwrap="p" />
</div>
</div>
</template>::card
#header
Card title
Body content here.
::Summary
In Vue, render only the summary with the summary prop:
<MDCRenderer :body="result.excerpt ?? result.body" :data="result.data" /><Markdown summary>{{ markdown }}</Markdown>Prose components
Both MDC and Comark resolve Prose* components to override how standard HTML elements render. Unlike @nuxtjs/mdc, the Comark Nuxt module does not register components/prose/ globally. Pass the components with the components prop or defineMarkdownComponent(), or register the directory in nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@comark/vue'],
components: [{ path: '~/components/prose', global: true, pathPrefix: false }, '~/components'],
})Component names stay the same:
| Element | MDC component name | Comark component name |
|---|---|---|
<p> | ProseP | ProseP |
<h1> | ProseH1 | ProseH1 |
<a> | ProseA | ProseA |
<pre> | ProsePre | ProsePre |
<code> | ProseCode | ProseCode |
Internally, MDC converted tags to kebab-case (prose-p) before looking up ProseP. Comark looks up ProseP in PascalCase directly. Existing Prose*.vue components work unchanged once you register them.
code prop (or meta.lines) to ProsePre. Declare __node on your component and call textContent() from comark/utils to read the raw code for copy buttons or collapse thresholds. See Custom code block.Nuxt UI
If your project uses Nuxt UI, the @comark/vue Nuxt module registers Nuxt UI prose components automatically.
Nuxt UI also provides callout shorthands for ::callout{icon="..." color="..."}:
::note
Informational note.
::
::tip
A helpful tip.
::
::warning
Something to watch out for.
::
::caution
A critical warning.
::Each shorthand renders ::callout with its matching color and icon. Without Nuxt UI, use ::callout{...} or register your own callout components.
Component syntax
Block and inline component syntax is unchanged from MDC:
::alert{type="info"}
This works the same in both MDC and Comark.
::
:badge{label="New"}
:::card
#header
Card title
Body content.
:::Binding and data passing
Comark supports {{ }} text interpolation and runtime data through the binding plugin and data binding. Three parts work differently from MDC:
- Opt-in plugin and component. Register the
binding()parser plugin and pass theBindingcomponent to your renderer. - Namespaced paths. Prefix paths with
frontmatter.,data.,meta., orprops.instead of reading bare names from a flat object. - Render-time data. Pass runtime values to the renderer's
dataprop, not toparseMarkdown().
Inline {{ }} interpolation
<!-- MDC: bare paths from parse-time `data` -->
Hello {{ user.name }}, you have {{ count }} messages.<!-- Comark: qualified paths against the render context -->
Hello {{ data.user.name }}, you have {{ data.count }} messages.
<!-- Or from YAML frontmatter -->
Welcome, {{ frontmatter.user.name || guest }}.Register the plugin and component when rendering (Nuxt example):
<script setup lang="ts">
import binding, { Binding } from '@comark/vue/plugins/binding'
const markdown = 'Hello {{ data.user.name }}, you have {{ data.count }} messages.'
</script>
<template>
<Markdown
:value="markdown"
:plugins="[binding()]"
:components="{ Binding }"
:data="{ user: { name: 'Ada' }, count: 3 }"
/>
</template>Runtime data prop
// MDC: data merged at parse time
const result = await parseMarkdown(md, { data: { user, count } })// Comark: parse without data, pass data when rendering
const document = await parseMarkdown(md, { plugins: [binding()] })
// Vue / Nuxt
// <MarkdownDocument :value="document" :data="{ user, count }" :components="{ Binding }" />:prefixed component props (:label="data.user.name", :answer="frontmatter.theAnswer") resolve against the same context without the binding plugin. Add the plugin only when you need inline {{ path }} text interpolation or ::if conditionals with the If component.
|| fallback values, ::if and #else conditionals, and framework imports.Quick reference
| Task | MDC | Comark |
|---|---|---|
| Install (core only) | @nuxtjs/mdc | comark |
| Install (Nuxt) | @nuxtjs/mdc | @comark/vue |
| Nuxt module | @nuxtjs/mdc | @comark/vue |
| Global plugin config | mdc: { ... } in nuxt.config | None (configured per component) |
| Reusable configured component | Not supported | defineMarkdownComponent({ plugins, components }) |
| Reusable configured renderer | Not supported | defineMarkdownDocumentComponent({ components }) |
| Parse | parseMarkdown(md) | parseMarkdown(md) |
| Render to Markdown | stringifyMarkdown(body, data) | renderMarkdown(document) |
| Reusable parser | await createMarkdownParser(opts) | createMarkdownParser(opts) |
| AST root | result.body (MDCRoot object) | document.nodes (tuple array) |
| Frontmatter | result.data | document.frontmatter |
| TOC | result.toc (built-in) | document.meta.toc (toc plugin) |
| Excerpt | result.excerpt (built-in) | document.meta.summary (summary plugin) |
| Renderer | <MDCRenderer :body :data> | <MarkdownDocument :value> |
| All-in-one | <MDC :value> | <Markdown :value> |
| Highlight | mdc.highlight in nuxt.config | shiki() plugin in defineMarkdownComponent |
Binding {{ var }} | Built-in, bare paths and parse-time data | binding() and Binding; paths such as data.x or frontmatter.x; render-time :data |
| Prop data binding | Parse-time data and {{ }} | :prop="path", resolved against frontmatter, meta, data, or props |
| Prose components | components/prose/Prose*.vue, registered by the module | Prose* components, registered by your app |
| Render slot | <MDCSlot /> | <slot /> |
| Unwrap slot | <MDCSlot unwrap="p" /> or <slot mdc-unwrap="p" /> | <slot unwrap="p" /> |
| Streaming | Not supported | streaming prop and autoClose |
Why Comark?
Comark gives JavaScript applications one Markdown pipeline for standards-based parsing, serializable documents, multiple renderers, plugins, and streaming.
Migration from MDX
Map every MDX concept (components, props, expressions, imports, and exports) to its Comark equivalent, with a step-by-step migration checklist.