mdx-marimo

Run marimo wherever MDX runs.

Compose reactive Python, SQL, and Markdown cells inside documentation, tutorials, and articles. Every marimo cell on a page shares one reactive namespace while the host keeps control of the surrounding MDX layout and theme.

Install

pnpm add @marimo-team/mdx-marimo

Configure MDX

Add remarkMarimo to the host's remark plugins:

import { remarkMarimo } from "@marimo-team/mdx-marimo/remark";

export default {
  remarkPlugins: [remarkMarimo],
};

Import the stylesheet once:

import "@marimo-team/mdx-marimo/styles.css";

React applications register the browser runtime from a client component:

"use client";

import { MarimoIslandRuntime } from "@marimo-team/mdx-marimo/react";

export function MdxRuntime() {
  return <MarimoIslandRuntime />;
}

Astro, Vue, and other browser entries can register the custom element directly:

import "@marimo-team/mdx-marimo/element/auto";

Publishing adapters can use the host-neutral page protocol and browser bridge from the same package:

import { mountMarimoIsland } from "@marimo-team/mdx-marimo/bridge/browser";
import {
  projectPageCellPayloads,
  type CompiledMarimoPage,
} from "@marimo-team/mdx-marimo/bridge/protocol";

Write marimo cells

```python marimo
import marimo as mo

slider = mo.ui.slider(1, 10, label="items")
slider
```

This paragraph is ordinary MDX.

```python marimo
mo.md(f"The slider is set to **{slider.value}**.")
```

Both cells belong to the same marimo notebook. The build includes their initial output in the page, then Pyodide hydrates them in the browser.

Declare page dependencies in one marimo-config fence:

```marimo-config
requires-python = ">=3.12"
dependencies = ["altair", "pandas"]
```

Cell options follow the marimo marker:

```python marimo echo=true output=true
chart
```

See the documentation for framework setup, all cell options, styling properties, and public APIs.

Working integrations are available for Astro, Docusaurus, Next.js, Nuxt, React, VitePress, and Vue.