Migrating from MDC

Step-by-step guide for moving from @nuxtjs/mdc to Comark, covering package mapping, API changes, component registration, and renderer setup.

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 synchronous createMarkdownParser() (no await)
  • AST: object tree → compact tuples ['tag', props, ...children]
  • Result: result.body and result.data → document.nodes and document.frontmatter
  • Renderer: <MDCRenderer :body :data> → <MarkdownDocument :value>
  • All-in-one: <MDC :value> → <Markdown :value>
  • Slots: <MDCSlot /> → native <slot />
  • Plugins: global nuxt.config → per-component defineMarkdownComponent({ plugins })
  • Binding: {{ path }} via opt-in binding plugin and render-time data prop (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:

Terminal
npx skills add https://comark.dev/skills/migrate-mdc-to-comark

Package changes

If you only use the programmatic API (parse functions, plugins, AST utilities), install comark:

npm uninstall @nuxtjs/mdc
npm install comark

If 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/vue

Core 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)

Reusable parser

import { createMarkdownParser } from '@nuxtjs/mdc/runtime'
const parser = await createMarkdownParser(options)
const result = await parser(markdown)

createMarkdownParser() is synchronous and returns the parser right away. MDC's factory was async because it initialized a unified pipeline.

See the Parse API for parser options and return types.

Render functions

Serialize back to Markdown

import { stringifyMarkdown } from '@nuxtjs/mdc/runtime'
const markdown = stringifyMarkdown(result.body, result.data)

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
}
MDCComark
result.bodydocument.nodes
result.datadocument.frontmatter
result.data.titledocument.frontmatter.title
result.tocdocument.meta.toc (requires toc plugin)
result.excerptdocument.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' }
  ]
}

Node checks and property access map as follows:

MDCComark
node.type === 'element'Array.isArray(node)
node.type === 'text'typeof node === 'string'
node.tagnode[0]
node.propsnode[1]
node.childrennode.slice(2)

Update custom AST walkers to use tuple indexing, or traverse documents with visit() from comark/utils.

See the document model guide for node types, parsed document structure, and traversal helpers.

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({ /* ... */ }),
        },
      },
    },
  },
})

Table of contents

import { parseMarkdown } from '@nuxtjs/mdc/runtime'
const result = await parseMarkdown(md, { toc: { depth: 3 } })
const toc = result.toc

Excerpt and summary

const result = await parseMarkdown(md)
const excerpt = result.excerpt  // MDCRoot | undefined

Emoji

// enabled by default via remark-emoji
// mdc: { remarkPlugins: { 'remark-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,
}

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.

See the plugins guide for built-in plugins and custom plugin hooks.

Nuxt module

Configuration

export default defineNuxtConfig({
  modules: ['@nuxtjs/mdc'],
  mdc: { highlight: { ... }, remarkPlugins: { ... } },
})

@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" />

Props that changed:

MDC <MDCRenderer>Comark <MarkdownDocument>Notes
body (MDCRoot)value (MarkdownDocument)Takes the full MarkdownDocument (see AST format)
data (frontmatter)RemovedFrontmatter lives on document.frontmatter
Not supporteddataRuntime values for data binding and {{ }}, not frontmatter
tagRemovedWrapper is <div class="comark-content">
proseRemovedProse* component resolution is automatic
unwrapunwrap prop or parse option<Markdown unwrap /> or :options="{ unwrap: 'p' }". See inline rendering
classRemovedStyle the wrapper via CSS
componentscomponentsSame purpose and shape
Not supportedcomponentsManifestAsync component resolver
Not supportedstreamingStreaming mode
Not supportedeffectsStream 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 -->

For a pre-parsed document, use <MarkdownDocument> instead of passing it to <Markdown>.

See Vue and Nuxt rendering for the component API, streaming setup, and SSR examples.

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:

composables/markdown.ts
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',
})
pages/article/[slug].vue
<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:

composables/markdown.ts
export const ArticleMarkdownDocument = defineMarkdownDocumentComponent({
  name: 'ArticleMarkdownDocument',
  components: {
    alert: CustomAlert,
    ProsePre,
  },
})
pages/article/[slug].vue
<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>

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

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

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:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@comark/vue'],
  components: [{ path: '~/components/prose', global: true, pathPrefix: false }, '~/components'],
})

Component names stay the same:

ElementMDC component nameComark component name
<p>ProsePProseP
<h1>ProseH1ProseH1
<a>ProseAProseA
<pre>ProsePreProsePre
<code>ProseCodeProseCode

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.

Comark does not pass a 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.
:::
See Component syntax for blocks, inline components, props, slots, and nesting.

Binding and data passing

Comark supports {{ }} text interpolation and runtime data through the binding plugin and data binding. Three parts work differently from MDC:

  1. Opt-in plugin and component. Register the binding() parser plugin and pass the Binding component to your renderer.
  2. Namespaced paths. Prefix paths with frontmatter., data., meta., or props. instead of reading bare names from a flat object.
  3. Render-time data. Pass runtime values to the renderer's data prop, not to parseMarkdown().

Inline {{ }} interpolation

<!-- MDC: bare paths from parse-time `data` -->
Hello {{ user.name }}, you have {{ count }} messages.

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 } })

: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.

See the binding plugin reference for || fallback values, ::if and #else conditionals, and framework imports.

Quick reference

TaskMDCComark
Install (core only)@nuxtjs/mdccomark
Install (Nuxt)@nuxtjs/mdc@comark/vue
Nuxt module@nuxtjs/mdc@comark/vue
Global plugin configmdc: { ... } in nuxt.configNone (configured per component)
Reusable configured componentNot supporteddefineMarkdownComponent({ plugins, components })
Reusable configured rendererNot supporteddefineMarkdownDocumentComponent({ components })
ParseparseMarkdown(md)parseMarkdown(md)
Render to MarkdownstringifyMarkdown(body, data)renderMarkdown(document)
Reusable parserawait createMarkdownParser(opts)createMarkdownParser(opts)
AST rootresult.body (MDCRoot object)document.nodes (tuple array)
Frontmatterresult.datadocument.frontmatter
TOCresult.toc (built-in)document.meta.toc (toc plugin)
Excerptresult.excerpt (built-in)document.meta.summary (summary plugin)
Renderer<MDCRenderer :body :data><MarkdownDocument :value>
All-in-one<MDC :value><Markdown :value>
Highlightmdc.highlight in nuxt.configshiki() plugin in defineMarkdownComponent
Binding {{ var }}Built-in, bare paths and parse-time databinding() and Binding; paths such as data.x or frontmatter.x; render-time :data
Prop data bindingParse-time data and {{ }}:prop="path", resolved against frontmatter, meta, data, or props
Prose componentscomponents/prose/Prose*.vue, registered by the moduleProse* components, registered by your app
Render slot<MDCSlot /><slot />
Unwrap slot<MDCSlot unwrap="p" /> or <slot mdc-unwrap="p" /><slot unwrap="p" />
StreamingNot supportedstreaming prop and autoClose
© 2026 Vercel, Inc.