Notebook cell outputs are not deterministic across rebuilds — cached outputs shown instead of fresh execution

[cschanhniem]

Problem

When using !marimo-embed or !marimo-inline directives, the cell outputs are generated at build time. However, on incremental builds during mkdocs serve, the HTML output served may contain cached cell outputs from the previous build rather than re-executing the notebook cells against the current file state.

This means:

1. A user edits a .py marimo notebook file referenced via !marimo-embed
2. On save, mkdocs serve triggers a dirty rebuild
3. The rebuilt page shows the old output (from the cache), not the output from the current notebook code
4. User has to restart mkdocs serve to see fresh outputs

Proposed investigation

The issue may be in how the MkDocs plugin cache interacts with file modification detection. Looking at the on_page_markdown flow:

• If the rendered output is cached by notebook file path + hash, dirty rebuilds may not invalidate that cache entry
• MkDocs provides page.file.abs_src_path and page.file.page modification timestamps, which could be compared against cached render timestamps

Suggested fix

Add a cache invalidation strategy based on file modification time:

# pseudocode
cache_key = (notebook_path, os.path.getmtime(notebook_path))
if cache_key not in render_cache:
    render_cache[cache_key] = render_notebook(notebook_path)

Alternatively, skip caching entirely during mkdocs serve dirty builds, similar to how some MkDocs plugins handle this.

This would make the development experience significantly smoother — currently you have to restart the server to see updated notebook outputs.