fix: preserve header

Author: dmadisetti

marimo/_ast/codegen.py

@@ -490,15 +490,46 @@ def generate_filecontents_from_ir(ir: NotebookSerializationV1) -> str:
     # Markdown frontmatter may contain non-config metadata (e.g., author,
     # description). Suppress warnings for unrecognized keys from markdown.
     silent = MarimoPath(ir.filename).is_markdown() if ir.filename else False
+    header_comments = _extract_header_comments(ir)
     return generate_filecontents(
         codes=[cell.code for cell in ir.cells],
         names=[cell.name for cell in ir.cells],
         cell_configs=[CellConfig.from_dict(cell.options) for cell in ir.cells],
         config=_AppConfig.from_untrusted_dict(ir.app.options, silent=silent),
-        header_comments=ir.header.value if ir.header else None,
+        header_comments=header_comments,
     )
 
 
+def _extract_header_comments(ir: NotebookSerializationV1) -> Optional[str]:
+    """Extract script preamble from header.
+
+    For markdown notebooks, Header.value may contain YAML-encoded frontmatter
+    metadata (with a 'header' key for the script preamble, and/or a
+    'pyproject' key for inline dependencies). For Python notebooks, it's the
+    raw script preamble.
+    """
+    if not ir.header or not ir.header.value:
+        return None
+    from marimo._utils import yaml
+
+    try:
+        parsed = yaml.load(ir.header.value)
+        if isinstance(parsed, dict):
+            # YAML dict means frontmatter metadata; extract script preamble
+            header = parsed.get("header", None)
+            pyproject = parsed.get("pyproject", None)
+            if header:
+                return str(header)
+            if pyproject:
+                from marimo._utils.scripts import wrap_script_metadata
+
+                return wrap_script_metadata(pyproject)
+            return None
+    except (yaml.YAMLError, AssertionError):
+        pass
+    return ir.header.value
+
+
 def generate_filecontents(
     codes: list[str],
     names: list[str],

marimo/_convert/markdown/from_ir.py

@@ -62,9 +62,18 @@ def convert_from_ir_to_markdown(
         }
     )
 
-    # Add header from notebook if present
+    # Recover frontmatter metadata from header
     if notebook.header and notebook.header.value:
-        metadata["header"] = notebook.header.value.strip()
+        try:
+            frontmatter = yaml.load(notebook.header.value)
+            if isinstance(frontmatter, dict):
+                # Insert metadata before config so config takes precedence
+                _recovered = dict(frontmatter)
+                _recovered.update(metadata)
+                metadata = _recovered
+        except (yaml.YAMLError, AssertionError):
+            # Not valid YAML dict — treat as script preamble
+            metadata["header"] = notebook.header.value.strip()
 
     # Add the expected qmd filter to the metadata.
     is_qmd = filename.endswith(".qmd")

marimo/_convert/markdown/to_ir.py

@@ -195,7 +195,12 @@ def strip(self) -> T:
 
 
 def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:
+    from marimo._ast.app_config import _AppConfig
+    from marimo._utils import yaml
+    from marimo._utils.scripts import wrap_script_metadata
+
     app_config = app_config_from_root(root)
+    config_only = _AppConfig.sanitize(app_config)
 
     sources: list[str] = []
     names: list[str] = []
@@ -208,14 +213,28 @@ def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:
         )
         sources.append(get_source_from_tag(child))
 
-    from marimo._utils.scripts import wrap_script_metadata
-
-    header = root.get("header", None)
+    header_str = root.get("header", None)
     pyproject = root.get("pyproject", None)
-    if pyproject and not header:
-        header = wrap_script_metadata(pyproject)
+
+    # Collect non-config frontmatter metadata
+    frontmatter = {k: v for k, v in app_config.items() if k not in config_only}
+    if pyproject:
+        frontmatter["pyproject"] = pyproject
+    if header_str:
+        frontmatter["header"] = header_str
+
+    # Build header: frontmatter YAML for md, or script preamble
+    if frontmatter:
+        header_value = yaml.dump(frontmatter, sort_keys=False)
+    elif pyproject and not header_str:
+        header_value = wrap_script_metadata(pyproject)
+    elif header_str:
+        header_value = header_str
+    else:
+        header_value = None
+
     notebook = NotebookSerializationV1(
-        app=AppInstantiation(options=app_config),
+        app=AppInstantiation(options=config_only),
         cells=[
             CellDef(
                 name=name,
@@ -224,7 +243,7 @@ def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:
             )
             for name, source, config in zip(names, sources, cell_config)
         ],
-        header=Header(value=header) if header else None,
+        header=Header(value=header_value) if header_value else None,
     )
     return SafeWrap(notebook)
 

marimo/_session/notebook/serializer.py

@@ -102,14 +102,21 @@ def deserialize(
         return convert_from_md_to_marimo_ir(content, filepath=filepath)
 
     def extract_header(self, path: Path) -> Optional[str]:
-        """Extract YAML frontmatter from Markdown file."""
-        from marimo._utils.inline_script_metadata import (
-            get_headers_from_markdown,
-        )
+        """Extract full frontmatter metadata from Markdown file as YAML.
+
+        Unlike Python files where only the script preamble matters, markdown
+        frontmatter can carry arbitrary metadata (author, description, tags,
+        etc.) that must survive through the save lifecycle. Return the full
+        frontmatter as YAML so _save_file() preserves it all.
+        """
+        from marimo._convert.markdown.to_ir import extract_frontmatter
+        from marimo._utils import yaml
 
         markdown = path.read_text(encoding="utf-8")
-        headers = get_headers_from_markdown(markdown)
-        return headers.get("header", None) or headers.get("pyproject", None)
+        frontmatter, _ = extract_frontmatter(markdown)
+        if not frontmatter:
+            return None
+        return yaml.dump(frontmatter, sort_keys=False)
 
 
 # Default format handlers

tests/_convert/markdown/test_markdown_conversion.py

@@ -172,6 +172,34 @@ def test_markdown_just_frontmatter() -> None:
     assert app.cell_manager.cell_data_at(ids[0]).code == ""
 
 
+def test_markdown_frontmatter_metadata_roundtrip() -> None:
+    """Frontmatter metadata should survive md -> IR -> md roundtrip."""
+    script = dedent(
+        remove_empty_lines(
+            """
+    ---
+    title: "My Title"
+    author: "Marimo Team"
+    description: "A notebook description"
+    ---
+
+    ```python {.marimo}
+    x = 1
+    ```
+    """
+        )
+    )
+
+    notebook_ir = convert_from_md_to_marimo_ir(script)
+    roundtripped = MarimoConvert.from_ir(notebook_ir).to_markdown()
+    assert "author: Marimo Team" in roundtripped
+    # Description is preserved but YAML may use folded style (>-)
+    from marimo._convert.markdown.to_ir import extract_frontmatter
+
+    meta, _ = extract_frontmatter(roundtripped)
+    assert meta["description"] == "A notebook description"
+
+
 @pytest.mark.requires("duckdb")
 def test_markdown_with_sql() -> None:
     script = dedent(