Migrating from MDX

Map every MDX concept (components, props, expressions, imports, and exports) to its Comark equivalent, with a step-by-step migration checklist.

This guide maps MDX concepts to Comark. Both let you place components in Markdown, and Comark uses plain-text directives instead of JSX.

Quick comparison

ConceptMDXComark
Block component<Alert>...</Alert>::alert ... ::
Inline component<Badge>text</Badge>:badge[text]
Props<Alert type="info">::alert{type="info"}
Self-closing<Divider />::divider\n::
Dynamic bindingyear={year}:year="data.year"
ChildrenJSX childrenMarkdown between :: delimiters
Importsimport X from './X'Component registered in renderer
Exportsexport const x = 1Frontmatter or application state

Components

Block components

MDX uses JSX tags. Comark uses :: fences:

<Alert type="info">
  This is an important message with **bold** text.
</Alert>

Inline components

Status: <Badge color="green">Active</Badge>

Self-closing components

<Divider />
<Chart color="#fcb32c" />

Nested components

<Card title="Example">
  <List>
    - Item 1
    - Item 2
  </List>
</Card>

Nesting in Comark adds one colon per level, such as :: for the outer block, ::: for a child, and :::: for deeper levels.

Props and attributes

Static props

<Alert type="info" dismissible>
  Content
</Alert>

Dynamic and expression binding

MDX uses JSX curly-brace expressions. Comark uses :prop="path" data binding:

<Chart year={currentYear} data={chartData} />

A : prefix parses the attribute value as JSON at render time. When the value isn't valid JSON, the renderer resolves it as a path on { frontmatter, meta, data, props }.

Numeric and boolean props

<Grid columns={3} fluid={true} />

Boolean props without a value default to true in both formats.

Imports and component registration

MDX imports components in each file. In Comark, you register components once in the renderer:

import Alert from './components/Alert'
import Chart from './components/Chart'

# Dashboard

<Alert type="info">Welcome!</Alert>

<Chart data={metrics} />

To share defaults across pages, create a configured component with defineMarkdownComponent:

import { defineMarkdownComponent } from '@comark/vue' // or '@comark/react'
import Alert from './components/Alert'
import Chart from './components/Chart'

export const DocsMarkdown = defineMarkdownComponent({
  name: 'DocsMarkdown',
  components: { Alert, Chart },
})

Exports and state

MDX uses export statements to define page-level variables:

export const year = 2023

# Report for {year}

Comark doesn't run JavaScript inside Markdown. Use frontmatter (with the binding plugin) for static metadata and application state for dynamic values:

---
year: 2023
---

# Report for {{ frontmatter.year }}

Expressions in text

MDX evaluates JavaScript expressions in prose:

The result is {2 + 3}.
Today is {new Date().toLocaleDateString()}.

Comark does not evaluate inline JavaScript expressions. Compute values in application code and interpolate them into the string before parsing, or pass them through the renderer's data prop with the binding plugin:

const result = 2 + 3
const today = new Date().toLocaleDateString()

const markdown = `
The result is ${result}.
Today is ${today}.
`

const tree = await parseMarkdown(markdown)

Layouts

MDX sets a layout component through a default export:

export { default } from './layouts/BlogPost'

# My Post

In Comark, wrap the renderer in your layout component:

<template>
  <BlogPostLayout>
    <Suspense>
      <Markdown>{{ content }}</Markdown>
    </Suspense>
  </BlogPostLayout>
</template>

Markdown features

Standard Markdown works the same way in both formats:

  • Headings, paragraphs, and lists
  • Bold, italic, and strikethrough
  • Links and images
  • Code blocks and inline code
  • Blockquotes
  • Tables
  • Horizontal rules

Migration checklist

  1. Replace JSX tags with Comark ::component and :component syntax.
  2. Move per-file import statements to the renderer's components option.
  3. Convert expression props from prop={expr} to :prop="data.expr" or JSON literals such as :columns="3".
  4. Replace inline expressions {expr} with string interpolation before parsing or {{ data.path }} via the binding plugin.
  5. Move export values to YAML frontmatter or application state.
  6. Remove layout exports and wrap <Markdown> in your layout component.
  7. Register plugins (shiki, math, mermaid) in your parser or renderer setup.
© 2026 Vercel, Inc.