version: "1.0.2" name: migrate-mdc-to-comark description: >- Migrate a Nuxt project from @nuxtjs/mdc to Comark. Covers package changes, parse/render API mapping, AST format, Nuxt module config, components, slots, plugins, and Nuxt UI integration.

Migrate from @nuxtjs/mdc to Comark

@nuxtjs/mdc was Nuxt-only. Comark is its successor: the markdown syntax is fully compatible, your .md files need no changes. What changes is the JavaScript API.

The migration has two parts: Core Package (programmatic API) and Nuxt Module (components, slots, config).

Quick Overview

• Package: @nuxtjs/mdc → comark (core only) or @comark/nuxt (Nuxt module)
• Parse: parseMarkdown() → parse() · factory: createParse() (sync, no await)
• Render: stringifyMarkdown() → renderMarkdown() from comark/render
• AST: object tree → compact tuples ['tag', props, ...children]
• Result: result.body / result.data → tree.nodes / tree.frontmatter
• Renderer: <MDCRenderer :body :data> → <MarkdownParsed :value>
• All-in-one: <MDC :value> → <Markdown :value>
• Slots: <MDCSlot /> → native <slot />
• Plugins: global nuxt.config → per-component defineMarkdownComponent({ plugins })
• Markdown files: no changes needed

Core Package

API Mapping

AST Format

Parse Options

// Before: MDCParseOptions
{
  remark: { plugins: { /* record */ } },
  rehype: { options: {...}, plugins: { /* record */ } },
  highlight: { theme: '...', langs: [...] } | false,
  toc: { depth: 3, searchDepth: 2 } | false,
}
// After: ParseOptions
{
  plugins: ComarkPlugin[],   // ordered array, not a record
  autoUnwrap: true,          // removes <p> from single-paragraph containers
  autoClose: true,           // completes incomplete syntax (useful for streaming)
  html: true,                // parse embedded HTML tags
}

Plugins

The unified/remark/rehype pipeline is replaced by Comark's own lighter plugin interface.

Available plugins: comark/plugins/toc, comark/plugins/highlight, comark/plugins/emoji, comark/plugins/task-list, comark/plugins/summary, comark/plugins/security, comark/plugins/alert, comark/plugins/math, comark/plugins/mermaid, comark/plugins/punctuation

Nuxt Module

Configuration

// Before
export default defineNuxtConfig({
  modules: ['@nuxtjs/mdc'],
  mdc: { highlight: { ... }, remarkPlugins: { ... } },
})
// After
export default defineNuxtConfig({
  modules: ['@comark/nuxt'],
  // No plugin config here (plugins are defined per-component)
})

@comark/nuxt auto-imports: Markdown, MarkdownParsed, defineMarkdownComponent, defineMarkdownParsedComponent.

Components

For a pre-parsed tree, use <MarkdownParsed> directly instead of <Markdown>.

<MarkdownParsed> props changes

Summary rendering

<!-- Before -->
<MDCRenderer :body="result.excerpt ?? result.body" :data="result.data" />
 
<!-- After -->
<Markdown summary>{{ markdown }}</Markdown>

defineMarkdownComponent

Replaces global mdc: { ... } config. Define reusable components with their own plugins and component mappings:

import { defineMarkdownComponent } from '@comark/vue'
import highlight from 'comark/plugins/highlight'
import toc from 'comark/plugins/toc'
export const ArticleComark = defineMarkdownComponent({
  name: 'ArticleComark',
  plugins: [highlight({ themes: { light: 'github-light', dark: 'github-dark' } }), toc()],
  components: { alert: CustomAlert },
})

Slots

<MDCSlot /> → native <slot />. Named slots work the same (#slotName in markdown, <slot name="slotName"> in component). The unwrap attribute (<slot unwrap="p">) strips wrapper tags from children.

Prose Components

Same Prose*.vue naming convention in components/prose/. Resolution changed from kebab-case (prose-p) to PascalCase (ProseP) internally. No file changes needed.

Nuxt UI Integration

When using Nuxt UI, @comark/nuxt registers Nuxt UI prose components automatically. Shorthand callout components are available:

::note    (informational)
::tip     (helpful suggestion)
::warning (something to watch out for)
::caution (critical warning)

These are only available with Nuxt UI. Without it, use ::callout{icon="..." color="..."}.

Common Pitfalls

1. `createParse` is sync: no await needed (unlike createMarkdownParser)
2. Attribute naming: Comark uses attrs.lang, not attrs.language
3. Frontmatter: stored in tree.frontmatter, not passed separately
4. `renderMarkdown` includes frontmatter: reads tree.frontmatter automatically
5. No `unified` pipeline: mdc.config.ts hooks (pre, remark, rehype, post) have no equivalent, use ComarkPlugin interface instead
6. Emoji is opt-in: not enabled by default like in MDC's remark-emoji

Component Syntax

The MDC block and inline component syntax is identical, so no changes are needed in .md files.

Unsupported Features

• Binding syntax ({{ variable }}): not supported, rendered as plain text
• Props binding / data passing: no equivalent for parseMarkdown(md, { data: { ... } })