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.

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.yaml
index 72ebe168ef..e0a213fc67 100644
--- a/.github/workflows/test_cli.yaml
+++ b/.github/workflows/test_cli.yaml
@@ -199,14 +199,14 @@ jobs:
shell: bash
run: |
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 check
shell: bash
run: |
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 diff
if [[ -n "$(git status --porcelain marimo/_tutorials)" ]]; then
diff --git a/marimo/_ast/load.py b/marimo/_ast/load.py
index 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 definition
return 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.py
index 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.py
index 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_VIOLATION
from marimo._utils import yaml
from 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.py
index cbdb8fe93e..93f5573c90 100644
--- a/marimo/_lint/linter.py
+++ b/marimo/_lint/linter.py
@@ -191,8 +191,11 @@ class Linter:
file_status.skipped = True
file_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 = True
file_status.message = (
f"Skipped: {file_path} (not a marimo notebook)"
diff --git a/marimo/_tutorials/markdown_format.md b/marimo/_tutorials/markdown_format.md
index 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.6
author: Marimo Team
description: >-
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 format
By default, marimo notebooks are stored as pure Python files. However,
diff --git a/marimo/_utils/generated_with.py b/marimo/_utils/generated_with.py
index 4d596ca65a..7c20aeeecc 100644
--- a/marimo/_utils/generated_with.py
+++ b/marimo/_utils/generated_with.py
@@ -4,13 +4,18 @@ from __future__ import annotations
import re
GENERATED_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.py
index 0125bfab38..b592fd8f6e 100644
--- a/tests/_ast/test_load.py
+++ b/tests/_ast/test_load.py
@@ -59,6 +59,30 @@ x = 1
assert 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.fixture
def 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.py
index 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.py
index 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.py
index 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 True
assert 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."""