migrate-mdc-to-comark
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.
How do I install this agent skill?
npx skills add https://comark.dev --skill migrate-mdc-to-comarkIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
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/vue(Vue renderer and Nuxt module) - Parse:
parseMarkdown()→parseMarkdown()· factory:createMarkdownParser()(sync, no await) - Render:
stringifyMarkdown()→renderMarkdown()fromcomark/render - AST: object tree → compact tuples
['tag', props, ...children] - Result:
result.body/result.data→document.nodes/document.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-inbinding()plugin + render-timedataprop (namespaced paths:data.,frontmatter.,meta.,props.) - Markdown files: component syntax unchanged; update binding paths if you used bare MDC names
Core Package
API Mapping
@nuxtjs/mdc | comark |
|---|---|
parseMarkdown(md, opts) | parseMarkdown(md, opts) from comark |
createMarkdownParser(opts) (async) | createMarkdownParser(opts) (sync, no await) |
stringifyMarkdown(body, data) | renderMarkdown(document) from comark/render |
result.body (MDCRoot) | document.nodes (Node[]) |
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
@nuxtjs/mdc | comark |
|---|---|
{ type: 'root', children: MDCNode[] } | { nodes: Node[], frontmatter: {}, meta: {} } |
{ type: 'element', tag: 'p', props: {}, children: [] } | ['p', {}, ...children] |
{ type: 'text', value: 'hello' } | 'hello' (plain string) |
Parse Options
// Before: MDCOptions
{
remark: { plugins: { /* record */ } },
rehype: { options: {...}, plugins: { /* record */ } },
highlight: { theme: '...', langs: [...] } | false,
toc: { depth: 3, searchDepth: 2 } | false,
}
// After: ParserOptions
{
plugins: ComarkPlugin[], // ordered array, not a record
autoUnwrap: true, // removes <p> from single-paragraph containers
autoClose: true, // completes incomplete syntax (useful for streaming)
// HTML, components, attributes, alerts, task-list, frontmatter are on by default
}
Plugins
The unified/remark/rehype pipeline is replaced by Comark's own lighter plugin interface.
| Feature | Before | After |
|---|---|---|
| Syntax highlighting | rehypeHighlight via createMarkdownParser | shiki() from comark/plugins/shiki |
| Table of Contents | parseMarkdown(md, { toc: { depth: 3 } }) | toc({ depth: 3 }) plugin |
| Excerpt / Summary | result.excerpt (built-in) | summary() plugin → document.meta.summary |
| Emoji | remark-emoji (enabled by default) | emoji() plugin (opt-in) |
Available plugins include: toc, shiki, emoji, task-list, summary, security, alert, math, mermaid, punctuation, binding. Prefer framework paths in apps (@comark/vue/plugins/*); use comark/plugins/* only for bare parseMarkdown().
Nuxt Module
Configuration
// Before
export default defineNuxtConfig({
modules: ['@nuxtjs/mdc'],
mdc: { highlight: { ... }, remarkPlugins: { ... } },
})
// After
export default defineNuxtConfig({
modules: ['@comark/vue'],
// No plugin config here (plugins are defined per-component)
})
@comark/vue auto-imports: Markdown, MarkdownDocument, defineMarkdownComponent, defineMarkdownDocumentComponent.
Components
@nuxtjs/mdc | @comark/vue |
|---|---|
<MDCRenderer :body :data :components> | <MarkdownDocument :value :components> |
<MDC :value :parser-options> | <Markdown :value :options> or <Markdown>{{ md }}</Markdown> |
<MDCSlot /> | <slot /> |
<MDCSlot unwrap="p" /> | <slot unwrap="p" /> |
<slot mdc-unwrap="p" /> | <slot unwrap="p" /> |
For a pre-parsed document, use <MarkdownDocument> directly instead of <Markdown>.
<MarkdownDocument> props changes
MDC <MDCRenderer> | Comark <MarkdownDocument> | Notes |
|---|---|---|
body (MDCRoot) | value (MarkdownDocument) | Different AST shape |
data | — | Frontmatter is in value.frontmatter |
tag | — | Wrapper is always <div class="comark-content"> |
prose | — | Prose* resolution is automatic |
unwrap | unwrap prop / parse option | <Markdown unwrap /> or parse unwrap |
| — | data | Runtime values for data binding / {{ }} — not frontmatter |
components | components | Same purpose |
| — | componentsManifest | New: dynamic async component resolver |
| — | streaming | New: streaming mode |
| — | caret | New: animated caret for streaming |
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 shiki from '@comark/vue/plugins/shiki'
import toc from '@comark/vue/plugins/toc'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
export const ArticleMarkdown = defineMarkdownComponent({
name: 'ArticleMarkdown',
plugins: [shiki({ themes: { light: githubLight, dark: githubDark } }), 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. Resolution changed from kebab-case (prose-p) to PascalCase (ProseP) internally. The Comark Nuxt module does not register components/prose/ globally: pass the components through components / defineMarkdownComponent(), or add components: [{ path: '~/components/prose', global: true, pathPrefix: false }, '~/components'] to nuxt.config.ts.
Nuxt UI Integration
When using Nuxt UI, the @comark/vue Nuxt module 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
createMarkdownParseris sync: noawaitneeded (unlikecreateMarkdownParser)- Attribute naming: Comark uses
attrs.lang, notattrs.language - Frontmatter: stored in
document.frontmatter, not passed separately renderMarkdownincludes frontmatter: readsdocument.frontmatterautomatically- No
unifiedpipeline:mdc.config.tshooks (pre,remark,rehype,post) have no equivalent, useComarkPlugininterface instead - 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 for components, slots, and attributes.
Binding and data passing
Supported via the binding plugin + render-time data prop. Differences from MDC:
- Opt-in: register
binding()and the frameworkBindingcomponent. - Namespaced paths:
{{ data.user.name }},{{ frontmatter.title }}, not bare{{ user.name }}. - Data at render time: pass
:data="{ user, count }"on<Markdown>/<MarkdownDocument>. Do not pass{ data }intoparseMarkdown.
<script setup lang="ts">
import binding, { Binding } from '@comark/vue/plugins/binding'
</script>
<template>
<Markdown
:value="markdown"
:plugins="[binding()]"
:components="{ Binding }"
:data="{ user: { name: 'Ada' }, count: 3 }"
/>
</template>
:prefixed component props (:label="data.user.name") resolve without the binding plugin. Use the plugin for inline {{ path }} text (and renderer If for ::if).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/comark.dev/migrate-mdc-to-comark">View migrate-mdc-to-comark on skillZs</a>