Comark vs MDX

Comark parses component syntax at runtime with no build step, while MDX compiles Markdown to JSX at build time. Compare syntax, architecture, framework support, and streaming.

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

ComarkMDX
Component syntax::alert{type="info"}<Alert type="info"> (JSX)
Build stepNot required, parse at runtime or build timeRequired, compiles to JSX
Content sourceAny string: file, database, CMS, API, LLM streamFiles processed by your bundler
RenderersVue, React, Svelte, Angular, Nuxt, HTML, ANSIReact (other JSX runtimes via pragma)
StreamingautoClose completes unfinished syntax on every parseNot supported, expects complete documents
OutputCompact serializable ASTCompiled JavaScript module
Inline JavaScript expressionsNo, values come from frontmatter or app stateYes, full JSX expressions
Imports and exports in contentNo, components registered in the rendererYes
Plugin ecosystemComark plugins and markdown-it pluginsremark 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:

  1. Store raw Markdown, including components, in a database or CMS.
  2. Call parseMarkdown(markdown) on the server or in the browser.
  3. Send the compact AST to the client.
  4. 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} />

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

© 2026 Vercel, Inc.