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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
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.pyindex 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__.pyindex 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 MdxMarkdownFlavorfrom 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.pyindex 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, Protocolif 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.pynew file mode 100644index 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.pyindex 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)]breakdiff --git a/tests/_cli/test_cli_export.py b/tests/_cli/test_cli_export.pyindex 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+@staticmethoddef 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()+@staticmethoddef 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.pyindex 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"b & <c>"',+ ),+ (+ "notebook.qmd",+ "qmd",+ "```{marimo .python",+ 'name="a"b & <c>"',+ ),+ (+ "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"b & <c>"' 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