Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat(export): support `mdx` flavor in md export (#10116)

Péter Gyarmati991ee0226e45
diff --git a/marimo/_cli/export/commands.py b/marimo/_cli/export/commands.py
index 116355b3ea..f40d03bd52 100644
--- a/marimo/_cli/export/commands.py
+++ b/marimo/_cli/export/commands.py
@@ -407,7 +407,7 @@ Watch for changes and regenerate the script on modification:
)
@click.option(
"--flavor",
- type=click.Choice(["pymdown", "qmd", "mystmd"]),
+ type=click.Choice(["pymdown", "qmd", "mystmd", "mdx"]),
default=None,
help="Markdown flavor to export.",
)
diff --git a/marimo/_convert/markdown/flavor/__init__.py b/marimo/_convert/markdown/flavor/__init__.py
index 83a771397e..861cfcab2e 100644
--- a/marimo/_convert/markdown/flavor/__init__.py
+++ b/marimo/_convert/markdown/flavor/__init__.py
@@ -11,6 +11,7 @@ from marimo._convert.markdown.flavor.base import (
MarkdownFlavorName,
MarkdownImportDialect,
)
+from marimo._convert.markdown.flavor.mdx import MdxMarkdownFlavor
from marimo._convert.markdown.flavor.mystmd import (
MystmdMarkdownFlavor,
_MystmdMarkdownImportDialect,
@@ -24,6 +25,7 @@ if TYPE_CHECKING:
_PYMDOWN_MARKDOWN = PymdownMarkdownFlavor()
_QMD_MARKDOWN = QmdMarkdownFlavor()
_MYSTMD_MARKDOWN = MystmdMarkdownFlavor()
+_MDX_MARKDOWN = MdxMarkdownFlavor()
_MYSTMD_MARKDOWN_IMPORT = _MystmdMarkdownImportDialect()
_MARKDOWN_FLAVORS: Mapping[MarkdownFlavorName, MarkdownFlavor] = (
MappingProxyType(
@@ -31,6 +33,7 @@ _MARKDOWN_FLAVORS: Mapping[MarkdownFlavorName, MarkdownFlavor] = (
_PYMDOWN_MARKDOWN.name: _PYMDOWN_MARKDOWN,
_QMD_MARKDOWN.name: _QMD_MARKDOWN,
_MYSTMD_MARKDOWN.name: _MYSTMD_MARKDOWN,
+ _MDX_MARKDOWN.name: _MDX_MARKDOWN,
}
)
)
@@ -39,7 +42,13 @@ _MARKDOWN_IMPORT_DIALECTS: Mapping[
] = MappingProxyType({_MYSTMD_MARKDOWN_IMPORT.name: _MYSTMD_MARKDOWN_IMPORT})
# Filename inference handles target-specific markdown extensions.
_MARKDOWN_FLAVORS_BY_EXTENSION: Mapping[str, MarkdownFlavor] = (
- MappingProxyType({".myst.md": _MYSTMD_MARKDOWN, ".qmd": _QMD_MARKDOWN})
+ MappingProxyType(
+ {
+ ".myst.md": _MYSTMD_MARKDOWN,
+ ".qmd": _QMD_MARKDOWN,
+ ".mdx": _MDX_MARKDOWN,
+ }
+ )
)
# Download and auto-export filenames use the selected flavor's suffix.
_MARKDOWN_OUTPUT_EXTENSIONS: Mapping[MarkdownFlavorName, str] = (
@@ -48,6 +57,7 @@ _MARKDOWN_OUTPUT_EXTENSIONS: Mapping[MarkdownFlavorName, str] = (
"pymdown": "md",
"qmd": "qmd",
"mystmd": "myst.md",
+ "mdx": "mdx",
}
)
)
@@ -56,6 +66,7 @@ _MARKDOWN_FILENAME_SUFFIXES = (
".myst.md",
".markdown",
".qmd",
+ ".mdx",
".md",
)
diff --git a/marimo/_convert/markdown/flavor/base.py b/marimo/_convert/markdown/flavor/base.py
index d0ae9bb4f8..032f500414 100644
--- a/marimo/_convert/markdown/flavor/base.py
+++ b/marimo/_convert/markdown/flavor/base.py
@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, ClassVar, Literal, Protocol
if TYPE_CHECKING:
from collections.abc import Iterator
-MarkdownFlavorName = Literal["pymdown", "qmd", "mystmd"]
+MarkdownFlavorName = Literal["pymdown", "qmd", "mystmd", "mdx"]
def _escape_attribute(value: str) -> str:
diff --git a/marimo/_convert/markdown/flavor/mdx.py b/marimo/_convert/markdown/flavor/mdx.py
new file mode 100644
index 0000000000..ee46faa062
--- /dev/null
+++ b/marimo/_convert/markdown/flavor/mdx.py
@@ -0,0 +1,195 @@
+"""MDX markdown target flavor."""
+
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, ClassVar
+
+from marimo._convert.markdown.flavor.base import (
+ CodeCellBlock,
+ MarkdownCellBlock,
+ MarkdownExportDocument,
+ MarkdownFlavor,
+ MarkdownFlavorName,
+)
+from marimo._utils.typing import override
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator, Mapping
+
+_CONFIG_KEYS = {"header", "pyproject"}
+_SIMPLE_OPTION_VALUE_RE = re.compile(r"^[A-Za-z0-9_.:/+-]+$")
+_SCRIPT_METADATA_RE = re.compile(
+ r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s"
+ + r"(?P<content>(^#(| .*)$\s)+)^# ///$"
+)
+
+
+class MdxMarkdownFlavor(MarkdownFlavor):
+ """Render marimo notebooks as MDX for `mdx-marimo`.
+
+ Code cells use MDX info strings such as `python marimo echo=true`.
+ Script metadata is emitted through a `marimo-config` fence.
+ """
+
+ name: ClassVar[MarkdownFlavorName] = "mdx"
+
+ @override
+ def prepare_metadata(
+ self, metadata: dict[str, str | list[str]]
+ ) -> dict[str, str | list[str]]:
+ return {
+ key: value
+ for key, value in metadata.items()
+ if key not in _CONFIG_KEYS
+ }
+
+ @override
+ def render_preamble(self, document: MarkdownExportDocument) -> list[str]:
+ metadata = document.metadata
+ return [
+ *_mdx_frontmatter(self.prepare_metadata(metadata)),
+ *_mdx_config(metadata, document.header),
+ ]
+
+ @override
+ def render_document(self, document: MarkdownExportDocument) -> str:
+ def render_blocks() -> Iterator[str]:
+ previous_was_markdown = False
+
+ for block in document.blocks:
+ if isinstance(block, MarkdownCellBlock):
+ if previous_was_markdown:
+ yield "{/* */}"
+ previous_was_markdown = True
+ yield self.render_markdown(block)
+ continue
+
+ if previous_was_markdown:
+ yield ""
+ previous_was_markdown = False
+
+ yield self.render_code_cell(block)
+
+ return "\n".join(
+ [
+ *self.render_preamble(document),
+ *render_blocks(),
+ ]
+ ).strip()
+
+ @override
+ def render_markdown(self, block: MarkdownCellBlock) -> str:
+ return block.text
+
+ @override
+ def render_code_cell(self, cell: CodeCellBlock) -> str:
+ return self._render_code_fence(
+ cell.source,
+ {"language": cell.language, **cell.options},
+ )
+
+ def _render_code_fence(
+ self,
+ code: str,
+ attributes: dict[str, str] | None = None,
+ ) -> str:
+ attributes = dict(attributes or {})
+ language = attributes.pop("language", "python")
+ return _render_mdx_code_fence(code, language, attributes)
+
+
+def _mdx_frontmatter(metadata: Mapping[str, object]) -> list[str]:
+ from marimo._utils import yaml
+
+ filtered = {
+ key: value
+ for key, value in metadata.items()
+ if value is not None and value != "" and value != []
+ }
+ if not filtered:
+ return []
+
+ body = yaml.marimo_compat_dump(filtered, sort_keys=False).strip()
+ return ["---", body, "---", ""]
+
+
+def _mdx_config(
+ metadata: Mapping[str, object], document_header: str | None
+) -> list[str]:
+ header = str(metadata.get("header") or document_header or "").strip()
+ header, header_pyproject = _split_script_metadata(header)
+ pyproject = str(metadata.get("pyproject") or header_pyproject).strip()
+ config: list[str] = []
+
+ if pyproject:
+ guard = _fence_guard_for(pyproject)
+ config.extend([f"{guard}marimo-config", pyproject, guard, ""])
+
+ if header:
+ config.append(
+ _render_mdx_code_fence(header, "python", {"include": "false"})
+ )
+
+ return config
+
+
+def _split_script_metadata(header: str) -> tuple[str, str]:
+ pyproject = ""
+
+ def replace(match: re.Match[str]) -> str:
+ nonlocal pyproject
+ if match.group("type") != "script":
+ return match.group(0)
+ if not pyproject:
+ pyproject = _uncomment_script_metadata(
+ match.group("content")
+ ).strip()
+ return ""
+
+ return _SCRIPT_METADATA_RE.sub(replace, header).strip(), pyproject
+
+
+def _uncomment_script_metadata(content: str) -> str:
+ return "".join(
+ line[2:] if line.startswith("# ") else line[1:]
+ for line in content.splitlines(keepends=True)
+ )
+
+
+def _fence_guard_for(body: str) -> str:
+ guard = "```"
+ while guard in body:
+ guard += "`"
+ return guard
+
+
+def _mdx_option_token(key: str, value: object) -> str:
+ return f"{key.replace('_', '-')}={_mdx_option_value(value)}"
+
+
+def _render_mdx_code_fence(
+ code: str, language: str, attributes: Mapping[str, object]
+) -> str:
+ options = " ".join(
+ _mdx_option_token(key, value) for key, value in attributes.items()
+ )
+ guard = _fence_guard_for(code)
+ head = f"{guard}{language} marimo"
+ if options:
+ head = f"{head} {options}"
+
+ return f"{head}\n{code}\n{guard}\n"
+
+
+def _mdx_option_value(value: object) -> str:
+ text = str(value)
+ if _SIMPLE_OPTION_VALUE_RE.match(text):
+ return text
+ if '"' not in text:
+ return f'"{text}"'
+ if "'" not in text:
+ return f"'{text}'"
+ escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+ return f'"{escaped}"'
diff --git a/marimo/_convert/markdown/from_ir.py b/marimo/_convert/markdown/from_ir.py
index 951a629de3..15e44b2607 100644
--- a/marimo/_convert/markdown/from_ir.py
+++ b/marimo/_convert/markdown/from_ir.py
@@ -178,7 +178,7 @@ def _notebook_to_markdown_export_document(
def _format_filename_title(filename: str) -> str:
basename = os.path.basename(filename)
- for suffix in (".myst.md", ".markdown", ".qmd", ".md", ".py"):
+ for suffix in (".myst.md", ".markdown", ".qmd", ".mdx", ".md", ".py"):
if basename.endswith(suffix):
name = basename[: -len(suffix)]
break
diff --git a/tests/_cli/test_cli_export.py b/tests/_cli/test_cli_export.py
index 5fbca32791..a968a306a3 100644
--- a/tests/_cli/test_cli_export.py
+++ b/tests/_cli/test_cli_export.py
@@ -724,6 +724,14 @@ class TestExportMarkdown:
_assert_success(p)
assert "```{marimo .python" in p.output
+ @staticmethod
+ def test_export_markdown_with_mdx_flavor(
+ temp_marimo_file: str,
+ ) -> None:
+ p = _run_export("md", temp_marimo_file, "--flavor", "mdx")
+ _assert_success(p)
+ assert "```python marimo" in p.output
+
@staticmethod
def test_export_markdown_infers_qmd_from_output(
temp_marimo_file: str, tmp_path: Path
@@ -749,6 +757,17 @@ class TestExportMarkdown:
_assert_success(p)
assert "```{marimo} python" in output.read_text()
+ @staticmethod
+ def test_export_markdown_infers_mdx_from_output(
+ temp_marimo_file: str, tmp_path: Path
+ ) -> None:
+ output = tmp_path / "notebook.mdx"
+
+ p = _run_export("md", temp_marimo_file, "--output", str(output))
+
+ _assert_success(p)
+ assert "```python marimo" in output.read_text()
+
@staticmethod
def test_export_markdown_stdout_uses_default_flavor(
temp_marimo_file: str,
diff --git a/tests/_convert/markdown/test_markdown_from_ir.py b/tests/_convert/markdown/test_markdown_from_ir.py
index 32be1a2d9c..5e1219806b 100644
--- a/tests/_convert/markdown/test_markdown_from_ir.py
+++ b/tests/_convert/markdown/test_markdown_from_ir.py
@@ -22,6 +22,7 @@ def test_format_filename_title():
assert _format_filename_title("simple.py") == "Simple"
assert _format_filename_title("my-cool_notebook.md") == "My Cool Notebook"
assert _format_filename_title("notebook.myst.md") == "Notebook"
+ assert _format_filename_title("notebook.mdx") == "Notebook"
def test_get_sql_options_from_cell_basic():
@@ -326,6 +327,48 @@ def test_convert_from_ir_to_markdown_qmd_format():
)
+def test_convert_from_ir_to_markdown_mdx_format():
+ """Test that .mdx files use mdx-marimo fence format."""
+ from marimo._schemas.serialization import (
+ AppInstantiation,
+ CellDef,
+ Header,
+ NotebookSerializationV1,
+ )
+
+ notebook = NotebookSerializationV1(
+ app=AppInstantiation(options={"app_title": "MDX Demo"}),
+ cells=[
+ CellDef(
+ name="setup",
+ code="import marimo as mo",
+ options={"hide_code": True},
+ ),
+ CellDef(
+ name="view",
+ code='mo.md("# Ready")',
+ options={},
+ ),
+ ],
+ header=Header(
+ value=(
+ '# /// script\n# dependencies = ["polars"]\n# ///\nimport os'
+ )
+ ),
+ violations=[],
+ valid=True,
+ filename="notebook.py",
+ )
+
+ markdown = convert_from_ir_to_markdown(notebook, filename="notebook.mdx")
+
+ assert markdown.startswith("---\ntitle: MDX Demo\n")
+ assert '```marimo-config\ndependencies = ["polars"]\n```' in markdown
+ assert "```python marimo include=false\nimport os\n```" in markdown
+ assert "```python marimo hide-code=true name=setup" in markdown
+ assert "# Ready" in markdown
+
+
def test_convert_from_ir_to_markdown_explicit_flavor():
"""Test that explicit flavors override filename inference."""
app = App()
@@ -358,10 +401,13 @@ def test_convert_from_ir_to_markdown_explicit_flavor():
("source.py", "pymdown", "source.md"),
("source.py", "qmd", "source.qmd"),
("source.py", "mystmd", "source.myst.md"),
+ ("source.py", "mdx", "source.mdx"),
("source.qmd", "pymdown", "source.md"),
+ ("source.mdx", "pymdown", "source.md"),
("source.myst.md", "pymdown", "source.md"),
("source.myst.md", "mystmd", "source.myst.md"),
(None, "qmd", "notebook.qmd"),
+ (None, "mdx", "notebook.mdx"),
],
)
def test_markdown_output_filename(filename, flavor, expected):
@@ -369,16 +415,33 @@ def test_markdown_output_filename(filename, flavor, expected):
@pytest.mark.parametrize(
- ("filename", "flavor", "expected_head"),
+ ("filename", "flavor", "expected_head", "expected_name"),
[
- ("notebook.md", "pymdown", "```python"),
- ("notebook.qmd", "qmd", "```{marimo .python"),
+ (
+ "notebook.md",
+ "pymdown",
+ "```python",
+ 'name="a&quot;b &amp; &lt;c&gt;"',
+ ),
+ (
+ "notebook.qmd",
+ "qmd",
+ "```{marimo .python",
+ 'name="a&quot;b &amp; &lt;c&gt;"',
+ ),
+ (
+ "notebook.mdx",
+ "mdx",
+ "```python marimo",
+ "name='a\"b & <c>'",
+ ),
],
)
def test_convert_from_ir_to_markdown_escapes_code_cell_attributes(
filename: str,
flavor: str,
expected_head: str,
+ expected_name: str,
) -> None:
from marimo._schemas.serialization import (
AppInstantiation,
@@ -405,4 +468,32 @@ def test_convert_from_ir_to_markdown_escapes_code_cell_attributes(
)
assert expected_head in markdown
- assert 'name="a&quot;b &amp; &lt;c&gt;"' in markdown
+ assert expected_name in markdown
+
+
+def test_convert_from_ir_to_markdown_mdx_escapes_quoted_options() -> None:
+ from marimo._schemas.serialization import (
+ AppInstantiation,
+ CellDef,
+ NotebookSerializationV1,
+ )
+
+ notebook = NotebookSerializationV1(
+ app=AppInstantiation(options={}),
+ cells=[
+ CellDef(
+ name="a\"b'c\\d",
+ code="x = 1",
+ options={},
+ )
+ ],
+ violations=[],
+ valid=True,
+ filename="notebook.py",
+ )
+
+ markdown = convert_from_ir_to_markdown(
+ notebook, filename="notebook.mdx", flavor="mdx"
+ )
+
+ assert 'name="a\\"b\'c\\\\d"' in markdown