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
fix: prevent marimo check from formatting regular markdown files (#10138)
Dylan Madisetti98ee517cf291
diff --git a/.github/workflows/test_cli.yaml b/.github/workflows/test_cli.yamlindex 72ebe168ef..e0a213fc67 100644--- a/.github/workflows/test_cli.yaml+++ b/.github/workflows/test_cli.yaml@@ -199,14 +199,14 @@ jobs:shell: bashrun: |echo "Checking examples directory..."- uv run marimo check --ignore-scripts --strict examples/**.py+ uv run marimo check --ignore-scripts --strict examples/- name: Check tutorial quality with marimo checkshell: bashrun: |echo "Checking tutorials..."uv run marimo check --ignore-scripts --fix \- marimo/_tutorials/**.py >> /dev/null \+ marimo/_tutorials/ >> /dev/null \|| echo "Errors expected"# Fail if there's a git diffif [[ -n "$(git status --porcelain marimo/_tutorials)" ]]; thendiff --git a/marimo/_ast/load.py b/marimo/_ast/load.pyindex c2ff53fb3c..c29911b2f0 100644--- a/marimo/_ast/load.py+++ b/marimo/_ast/load.py@@ -12,6 +12,7 @@ from marimo._ast.parse import (MarimoFileError,NonMarimoPythonScriptError,all_violations_soft,+ is_non_marimo_markdown,is_non_marimo_python_script,)from marimo._schemas.serialization import (@@ -136,6 +137,13 @@ def get_notebook_status(filename: str) -> LoadResult:)# Only comments or a doc string — treat as empty per status definitionreturn LoadResult(status="empty", notebook=notebook, contents=contents)+ # Plain markdown (no marimo cells/metadata) parses into a "valid" notebook+ # of markdown cells, but is not a marimo notebook — flag it as invalid so+ # the linter leaves it untouched. NB. it can still be opened/bootstrapped.+ if is_non_marimo_markdown(notebook):+ return LoadResult(+ status="invalid", notebook=notebook, contents=contents+ )if len(notebook.violations) > 0:LOGGER.debug("Notebook has violations: \n%s",diff --git a/marimo/_ast/parse.py b/marimo/_ast/parse.pyindex 4668fe54a7..eb7421344a 100644--- a/marimo/_ast/parse.py+++ b/marimo/_ast/parse.py@@ -1197,6 +1197,7 @@ UNEXPECTED_STATEMENT_BODY_CELL_VIOLATION = (UNEXPECTED_KEYWORD_VALUE_VIOLATION = "Unexpected value for keyword argument"ONLY_HEADER_EXTRACTED_VIOLATION = "Only able to extract header."NON_MARIMO_PYTHON_SCRIPT_VIOLATION = "non-marimo Python content beyond header"+NON_MARIMO_MARKDOWN_VIOLATION = "markdown without marimo cells or metadata"EXPECTED_RUN_GUARD_VIOLATION = "Expected run guard statement"SCANNER_UNPARSABLE_CELL_VIOLATION = ("Cell contains a syntax error and could not be parsed"@@ -1223,3 +1224,10 @@ def is_non_marimo_python_script(notebook: NotebookSerialization) -> bool:(v.description == NON_MARIMO_PYTHON_SCRIPT_VIOLATION)for v in notebook.violations)+++def is_non_marimo_markdown(notebook: NotebookSerialization) -> bool:+ return any(+ (v.description == NON_MARIMO_MARKDOWN_VIOLATION)+ for v in notebook.violations+ )diff --git a/marimo/_convert/markdown/to_ir.py b/marimo/_convert/markdown/to_ir.pyindex 71c174fbeb..341b4d0ddf 100644--- a/marimo/_convert/markdown/to_ir.py+++ b/marimo/_convert/markdown/to_ir.py@@ -50,6 +50,7 @@ from marimo._schemas.serialization import (CellDef,Header,NotebookSerializationV1,+ Violation,)if TYPE_CHECKING:@@ -200,6 +201,7 @@ class SafeWrap(Generic[T]):def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:from marimo._ast.app_config import _AppConfig+ from marimo._ast.parse import NON_MARIMO_MARKDOWN_VIOLATIONfrom marimo._utils import yamlfrom marimo._utils.scripts import wrap_script_metadata@@ -237,6 +239,17 @@ def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:else:header_value = None+ # A markdown file is only recognized as a marimo notebook if it has at+ # least one marimo code cell (a `{python}`/`{sql}`/`{.marimo}` fence) or+ # marimo metadata in its frontmatter. Otherwise it is plain markdown, and+ # lint/fix should leave it untouched (see `is_non_marimo_markdown`).+ is_marimo = "marimo-version" in root.attrib or any(+ child.tag == MARIMO_CODE for child in root+ )+ violations = (+ [] if is_marimo else [Violation(NON_MARIMO_MARKDOWN_VIOLATION)]+ )+notebook = NotebookSerializationV1(app=AppInstantiation(options=config_only),cells=[@@ -250,6 +263,7 @@ def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:)],header=Header(value=header_value) if header_value else None,+ violations=violations,)return SafeWrap(notebook)diff --git a/marimo/_lint/linter.py b/marimo/_lint/linter.pyindex cbdb8fe93e..93f5573c90 100644--- a/marimo/_lint/linter.py+++ b/marimo/_lint/linter.py@@ -191,8 +191,11 @@ class Linter:file_status.skipped = Truefile_status.message = f"Skipped: {file_path} (empty file)"elif load_result.status == "invalid":- if self.ignore_scripts:- # Skip this file silently when ignore_scripts is enabled+ # Markdown is skipped unconditionally: `marimo check` globs all+ # `.md`/`.qmd` files, and most are plain documentation. Failing on+ # them (as with non-marimo Python scripts) would be too noisy.+ if self.ignore_scripts or file_path.endswith((".md", ".qmd")):+ # Skip this file silently when ignore_scripts is enabled (or for plain markdown).file_status.skipped = Truefile_status.message = (f"Skipped: {file_path} (not a marimo notebook)"diff --git a/marimo/_tutorials/markdown_format.md b/marimo/_tutorials/markdown_format.mdindex c7c675fa5e..75e0d68d11 100644--- a/marimo/_tutorials/markdown_format.md+++ b/marimo/_tutorials/markdown_format.md@@ -1,6 +1,4 @@----title: Markdown-marimo-version: 0.23.6author: Marimo Teamdescription: >-Markdown is a lightweight markup language with plain text formatting syntax. `marimo`@@ -16,7 +14,10 @@ pyproject: |-"pandas==2.3.3","pyarrow==23.0.0",]+title: Markdown+marimo-version: 0.23.13---+# Markdown file formatBy default, marimo notebooks are stored as pure Python files. However,diff --git a/marimo/_utils/generated_with.py b/marimo/_utils/generated_with.pyindex 4d596ca65a..7c20aeeecc 100644--- a/marimo/_utils/generated_with.py+++ b/marimo/_utils/generated_with.py@@ -4,13 +4,18 @@ from __future__ import annotationsimport reGENERATED_WITH_RE = re.compile(r"^__generated_with = .*$", re.MULTILINE)+# Markdown notebooks record the version in frontmatter instead.+MARIMO_VERSION_RE = re.compile(r"^marimo-version: .*$", re.MULTILINE)+++def _strip_version(contents: str) -> str:+ return MARIMO_VERSION_RE.sub(+ "", GENERATED_WITH_RE.sub("", contents)+ ).strip()def contents_differ_excluding_generated_with(original: str, generated: str) -> bool:- """Compare file contents while ignoring `__generated_with` differences."""- return (- GENERATED_WITH_RE.sub("", original).strip()- != GENERATED_WITH_RE.sub("", generated).strip()- )+ """Compare file contents while ignoring the recorded marimo version."""+ return _strip_version(original) != _strip_version(generated)diff --git a/tests/_ast/test_load.py b/tests/_ast/test_load.pyindex 0125bfab38..b592fd8f6e 100644--- a/tests/_ast/test_load.py+++ b/tests/_ast/test_load.py@@ -59,6 +59,30 @@ x = 1assert result.notebook.filename == str(notebook_path)+def test_plain_markdown_status_is_invalid(tmp_path):+ """Plain markdown (no marimo cells/metadata) is not a marimo notebook."""+ notebook_path = tmp_path / "README.md"+ notebook_path.write_text(+ "# My Project\n\nJust prose with a ```python``` sample.\n",+ encoding="utf-8",+ )++ result = load.get_notebook_status(str(notebook_path))++ assert result.status == "invalid"+++def test_plain_markdown_still_bootstraps_via_load_app(tmp_path):+ """`marimo edit README.md` must still open the prose, not an empty app."""+ notebook_path = tmp_path / "README.md"+ notebook_path.write_text("# My Project\n\nJust prose.\n", encoding="utf-8")++ app = load.load_app(str(notebook_path))++ assert app is not None+ assert len(list(app._cell_manager.cell_ids())) >= 1++@pytest.fixturedef unified_load():"""Uses the new unified load_app path with deserialization."""diff --git a/tests/_convert/markdown/test_markdown_conversion.py b/tests/_convert/markdown/test_markdown_conversion.pyindex 05d122957a..92e1423adc 100644--- a/tests/_convert/markdown/test_markdown_conversion.py+++ b/tests/_convert/markdown/test_markdown_conversion.py@@ -463,6 +463,65 @@ def test_no_frontmatter() -> None:assert len(ids) == 3+def test_plain_markdown_flagged_non_marimo() -> None:+ """Plain markdown parses as valid but carries a non-marimo violation."""+ from marimo._ast.parse import is_non_marimo_markdown++ plain = dedent(+ """+ # My Project++ Just prose with a fenced sample:++ ```python+ print("hello")+ ```+ """+ )+ notebook_ir = convert_from_md_to_marimo_ir(plain)+ # Still valid so it can be bootstrapped/opened, but flagged for the linter.+ assert notebook_ir.valid is True+ assert is_non_marimo_markdown(notebook_ir) is True+++def test_marimo_markdown_not_flagged_non_marimo() -> None:+ """Marimo fences or `marimo-version` frontmatter avoid the flag."""+ from marimo._ast.parse import is_non_marimo_markdown++ with_fence = dedent(+ remove_empty_lines(+ """+ # Title++ ```python {.marimo}+ x = 1+ ```+ """+ )+ )+ assert (+ is_non_marimo_markdown(convert_from_md_to_marimo_ir(with_fence))+ is False+ )++ with_version = dedent(+ remove_empty_lines(+ """+ ---+ title: Title+ marimo-version: 0.1.0+ ---++ # Just prose+ """+ )+ )+ assert (+ is_non_marimo_markdown(convert_from_md_to_marimo_ir(with_version))+ is False+ )++def test_markdown_just_frontmatter() -> None:script = dedent(remove_empty_lines(diff --git a/tests/_lint/test_generated_with_comparison.py b/tests/_lint/test_generated_with_comparison.pyindex 1aca9c726c..d99a76e126 100644--- a/tests/_lint/test_generated_with_comparison.py+++ b/tests/_lint/test_generated_with_comparison.py@@ -123,3 +123,46 @@ def test():# Should return True (one has __generated_with, one doesn't)assert contents_differ_excluding_generated_with(original, generated)+++def test_markdown_marimo_version_ignored():+ """Markdown notebooks record the version in frontmatter, not code."""++ original = """---+title: Notebook+marimo-version: 0.23.6+---++# Heading+"""++ generated = """---+title: Notebook+marimo-version: 0.23.13+---++# Heading+"""++ # Version-only frontmatter differences are not meaningful.+ assert not contents_differ_excluding_generated_with(original, generated)+++def test_markdown_real_changes_still_detected():+ """Real markdown differences are still detected despite version stripping."""++ original = """---+marimo-version: 0.23.6+---++# Heading+"""++ generated = """---+marimo-version: 0.23.13+---++# Different heading+"""++ assert contents_differ_excluding_generated_with(original, generated)diff --git a/tests/_lint/test_run_check.py b/tests/_lint/test_run_check.pyindex 55c6bdf12a..89c9a5164a 100644--- a/tests/_lint/test_run_check.py+++ b/tests/_lint/test_run_check.py@@ -108,10 +108,99 @@ def __():# files with simple comments are valid notebooks with errors.assert not py_result.failed+ # Plain markdown (no marimo cells/metadata) is skipped, not linted.assert not md_result.failed+ assert md_result.skipped is Trueassert txt_result.skipped is True # Not a notebook+class TestMarkdownRecognition:+ """Markdown is only linted when recognized as a marimo notebook."""++ PLAIN_README = """# My Project++A plain README with a fenced code sample:++```python+import foo+foo.bar()+```++Nothing marimo about it.+"""+ MARIMO_MD = """# Title++```python {.marimo}+x = 1+```+"""+ FRONTMATTER_ONLY = """---+title: Title+marimo-version: 0.1.0+---++# Just prose+"""++ def test_plain_markdown_is_skipped(self, tmpdir):+ md_file = Path(tmpdir) / "README.md"+ md_file.write_text(self.PLAIN_README)++ result = run_check((str(md_file),))++ assert len(result.files) == 1+ assert result.files[0].skipped is True+ assert result.errored is False+ assert result.issues_count == 0++ def test_plain_markdown_fix_is_noop(self, tmpdir):+ """`--fix` must not rewrite a plain README (the reported regression)."""+ md_file = Path(tmpdir) / "README.md"+ md_file.write_text(self.PLAIN_README)++ result = run_check((str(md_file),), fix=True)++ assert result.files[0].skipped is True+ assert result.fixed_count == 0+ assert md_file.read_text() == self.PLAIN_README++ def test_marimo_markdown_notebook_is_linted(self, tmpdir):+ """A md notebook with a marimo fence is recognized and fixable."""+ md_file = Path(tmpdir) / "notebook.md"+ md_file.write_text(self.MARIMO_MD)++ result = run_check((str(md_file),), fix=True)++ assert result.files[0].skipped is False+ # Frontmatter (title/marimo-version) is injected on fix.+ assert "marimo-version:" in md_file.read_text()++ def test_frontmatter_only_markdown_is_recognized(self, tmpdir):+ """`marimo-version` frontmatter marks a notebook even with no fences."""+ md_file = Path(tmpdir) / "notebook.md"+ md_file.write_text(self.FRONTMATTER_ONLY)++ result = run_check((str(md_file),))++ assert result.files[0].skipped is False++ def test_qmd_with_python_fence_is_linted(self, tmpdir):+ qmd_file = Path(tmpdir) / "notebook.qmd"+ qmd_file.write_text("# Title\n\n```{python}\nx = 1\n```\n")++ result = run_check((str(qmd_file),))++ assert result.files[0].skipped is False++ def test_plain_qmd_is_skipped(self, tmpdir):+ qmd_file = Path(tmpdir) / "doc.qmd"+ qmd_file.write_text("---\ntitle: Doc\n---\n\n# Just prose\n")++ result = run_check((str(qmd_file),))++ assert result.files[0].skipped is True++class TestFileStatus:"""Test the FileStatus class."""