---
title: "Comark vs MDX"
description: "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."
canonical_url: "https://comark.dev/compare/comark-vs-mdx"
---
# 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

|                                | 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:

```mdc
::alert{type="warning"}
This action cannot be undone.
::
```

Because `parseMarkdown(markdown)` returns a serializable [`MarkdownDocument`](https://comark.dev/getting-started/document-model), 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

::code-group
```jsx [MDX]
import Alert from './components/Alert'
import Chart from './components/Chart'

# Dashboard

<Alert type="info">
  Welcome back, with **bold** text inside.
</Alert>

<Chart data={metrics} />
```

```mdc [Comark]
# 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](https://comark.dev/kb/migration-from-mdx) 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](https://comark.dev/reference/auto-close) step closes unfinished syntax, such as open bold markers, code fences, and component blocks, before each parse:

```ts
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](https://comark.dev/plugins/custom/plugin-api) and accepts [markdown-it parsing plugins](https://comark.dev/plugins/custom/markdown-it).

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](https://comark.dev/kb/migration-from-mdx) maps every MDX concept (components, props, expressions, imports, exports, and layouts) to its Comark equivalent, with a checklist.

## FAQ

::accordion
  :::accordion-item{label="Is Comark a drop-in replacement for MDX?"}
  No. The component syntax differs (`::alert` instead of `<Alert>`), and inline JavaScript moves into your application code. The [migration guide](https://comark.dev/kb/migration-from-mdx) covers every mapping, and standard Markdown needs no changes.
  :::

  :::accordion-item{label="Can Comark run at build time like MDX?"}
  Yes. `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.
  :::

  :::accordion-item{label="Does Comark work with React Server Components?"}
  Yes. `@comark/react` supports Server Components and Next.js. See [Render Comark in React](https://comark.dev/rendering/react).
  :::

  :::accordion-item{label="Can I keep using remark or rehype plugins?"}
  Not directly. Comark is built on markdown-exit, a TypeScript rewrite of markdown-it, so you can use [markdown-it plugins](https://comark.dev/plugins/custom/markdown-it) or the [Comark plugin API](https://comark.dev/plugins/custom/plugin-api). Built-in plugins cover Shiki and Rangi highlighting, KaTeX math, Mermaid diagrams, tables of contents, alerts, and footnotes.
  :::
::

---

- [Migrate from MDX](https://comark.dev/kb/migration-from-mdx)
- [Playground](https://comark.dev/play)


## Sitemap

See the full [sitemap](https://comark.dev/sitemap.md) for all pages.
