Comark vs MDX
TL;DR: Both let you use components in Markdown. MDX compiles content to JSX at build time, which ties it to a bundler and a JSX runtime. Comark parses component syntax at runtime into a JSON-safe document, so content can come from files, a database, a CMS, or an AI stream, and render in Vue, React, Svelte, Angular, HTML, or the terminal.
At a glance
| Comark | MDX | |
|---|---|---|
| Component syntax | ::alert{type="info"} | <Alert type="info"> (JSX) |
| Build step | Not required, parse at runtime or build time | Required, compiles to JSX |
| Content source | Any string: file, database, CMS, API, LLM stream | Files processed by your bundler |
| Renderers | Vue, React, Svelte, Angular, Nuxt, HTML, ANSI | React (other JSX runtimes via pragma) |
| Streaming | autoClose completes unfinished syntax on every parse | Not supported, expects complete documents |
| Output | Compact serializable AST | Compiled JavaScript module |
| Inline JavaScript expressions | No, values come from frontmatter or app state | Yes, full JSX expressions |
| Imports and exports in content | No, components registered in the renderer | Yes |
| Plugin ecosystem | Comark plugins and markdown-it plugins | remark and rehype plugins |
Content vs code
An .mdx file is a JavaScript module. It can import components, export values, and evaluate JavaScript expressions. Because MDX is code, every change must run through a compiler before it renders. Fixing a typo in git triggers a rebuild, and serving MDX from a database requires compiling JavaScript on the server.
Comark keeps content as plain text:
::alert{type="warning"}
This action cannot be undone.
::Because parseMarkdown(markdown) returns a serializable MarkdownDocument, CMS content renders without a build pipeline:
- Store raw Markdown, including components, in a database or CMS.
- Call
parseMarkdown(markdown)on the server or in the browser. - Send the compact AST to the client.
- Render it with a components map:
<MarkdownDocument :value="ast" :components="{ Alert }" />.
Saved edits render on the next request without a rebuild.
Syntax side by side
import Alert from './components/Alert'
import Chart from './components/Chart'
# Dashboard
<Alert type="info">
Welcome back, with **bold** text inside.
</Alert>
<Chart data={metrics} /># Dashboard
::alert{type="info"}
Welcome back, with **bold** text inside.
::
::chart{:data="data.metrics"}
::Comark registers components once in the renderer instead of importing them in each file. Dynamic props such as :data="data.metrics" read from frontmatter or the renderer's data prop. See the migration guide for the full mapping.
Streaming
LLMs emit Markdown token by token. MDX cannot compile an unterminated document, so streaming MDX means waiting for the full response or accepting compile errors mid-stream.
Comark's auto-close step closes unfinished syntax, such as open bold markers, code fences, and component blocks, before each parse:
import { autoCloseMarkdown } from 'comark'
autoCloseMarkdown('**bold text') // '**bold text**'
autoCloseMarkdown('::alert\nContent') // '::alert\nContent\n::'Each framework renderer exposes a streaming prop that reuses completed blocks while tokens arrive, including custom components.
What MDX does that Comark doesn't
MDX supports features that Comark omits by design:
- Inline JavaScript expressions:
{2 + 3}or{new Date().toLocaleDateString()}evaluate in MDX. In Comark, compute values in application code and pass them through frontmatter, bindings, or string interpolation. - Imports and exports in content: MDX files are modules. Comark content is data, and components live in your app.
- The remark and rehype ecosystem: MDX runs remark and rehype plugins directly. Comark has its own plugin API and accepts markdown-it parsing plugins.
If developers write your content in git and embed custom JavaScript logic per page, MDX fits. If content comes from writers, a CMS, an API, or a language model, Comark keeps it as plain data with no compiler step.
Migrating
The MDX migration guide maps every MDX concept (components, props, expressions, imports, exports, and layouts) to its Comark equivalent, with a checklist.
FAQ
::alert instead of <Alert>), and inline JavaScript moves into your application code. The migration guide covers every mapping, and standard Markdown needs no changes.parseMarkdown() runs anywhere JavaScript runs. You can parse at build time and ship the AST, parse on the server per request, or parse in the browser with the same function.@comark/react supports Server Components and Next.js. See Render Comark in React.Markdown for AI chat
Compare Streamdown, Markstream, Comark, @humanspeak/svelte-markdown, markdown-to-jsx, and plain parsers for rendering streamed LLM output. See how each handles incomplete Markdown, components, security, and frameworks.
Comark vs react-markdown
Comark adds component syntax, streaming auto-close, and multi-framework rendering that react-markdown lacks. Compare architecture, component mapping, and streaming behavior.