Migrating from MDX
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
| Concept | MDX | Comark |
|---|---|---|
| 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 binding | year={year} | :year="data.year" |
| Children | JSX children | Markdown between :: delimiters |
| Imports | import X from './X' | Component registered in renderer |
| Exports | export const x = 1 | Frontmatter 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>::alert{type="info"}
This is an important message with **bold** text.
::Inline components
Status: <Badge color="green">Active</Badge>Status: :badge[Active]{color="green"}Self-closing components
<Divider />
<Chart color="#fcb32c" />::divider
::
::chart{color="#fcb32c"}
::Nested components
<Card title="Example">
<List>
- Item 1
- Item 2
</List>
</Card>::card{title="Example"}
:::list
- Item 1
- Item 2
:::
::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>::alert{type="info" dismissible}
Content
::Dynamic and expression binding
MDX uses JSX curly-brace expressions. Comark uses :prop="path" data binding:
<Chart year={currentYear} data={chartData} />::chart{:year="data.currentYear" :data="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} />::grid{:columns="3" fluid}
::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} /><script setup>
import { Markdown } from '@comark/vue'
import Alert from './components/Alert.vue'
import Chart from './components/Chart.vue'
const markdown = `
# Dashboard
::alert{type="info"}
Welcome!
::
::chart{:data="data.metrics"}
::
`
</script>
<template>
<Suspense>
<Markdown :components="{ Alert, Chart }" :data="{ metrics }">{{ markdown }}</Markdown>
</Suspense>
</template>import { Markdown } from '@comark/react'
import { Alert } from './components/Alert'
import { Chart } from './components/Chart'
const markdown = `
# Dashboard
::alert{type="info"}
Welcome!
::
::chart{:data="data.metrics"}
::
`
export default function Page() {
return <Markdown components={{ Alert, Chart }} data={{ metrics }}>{markdown}</Markdown>
}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 }}<script setup>
const year = ref(2023)
const markdown = computed(() => `# Report for ${year.value}`)
</script>
<template>
<Suspense>
<Markdown>{{ markdown }}</Markdown>
</Suspense>
</template>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 PostIn 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
- Replace JSX tags with Comark
::componentand:componentsyntax. - Move per-file
importstatements to the renderer'scomponentsoption. - Convert expression props from
prop={expr}to:prop="data.expr"or JSON literals such as:columns="3". - Replace inline expressions
{expr}with string interpolation before parsing or{{ data.path }}via the binding plugin. - Move
exportvalues to YAML frontmatter or application state. - Remove layout exports and wrap
<Markdown>in your layout component. - Register plugins (
shiki,math,mermaid) in your parser or renderer setup.