perf/fix: markdown singleton to mitigate reported race condition

[dmadisetti]

📝 Summary

closes #9332

Cache the markdown render object, calling reset between uses. This should be a slight performance gain, and help mitigate an observed crash.

---

Unable to replicate the reported issue, but did see a genuine speedup

┌─────────────────────┬──────────────────────────┬───────────────────────────────┐
│       Metric        │ main (per-call Markdown) │ dm/md-race (singleton + lock) │
├─────────────────────┼──────────────────────────┼───────────────────────────────┤
│ Exceptions          │ 0                        │ 0                             │
├─────────────────────┼──────────────────────────┼───────────────────────────────┤
│ Sequential time     │ 510 ms                   │ 49 ms                         │
├─────────────────────┼──────────────────────────┼───────────────────────────────┤
│ Concurrent time     │ 462 ms                   │ 54 ms                         │
├─────────────────────┼──────────────────────────┼───────────────────────────────┤
│ Unique footnote IDs │ 1 / 200 ❌               │ 200 / 200 ✅                  │
└─────────────────────┴──────────────────────────┴───────────────────────────────┘

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 12, 2026 9:34pm

[Copilot]

Pull request overview

This PR changes marimo’s Markdown rendering to reuse a cached markdown.Markdown instance (resetting it between renders) and adds locking to mitigate a reported concurrency-related crash (#9332). It also updates tests to account for the footnotes extension’s variable per-render unique ID prefix.

Changes:

• Introduce a cached Markdown renderer plus a lock, and route _md rendering through the shared renderer after calling reset().
• Adjust the footnotes test to validate output structure via regex instead of asserting an exact unique-id prefix.
• Update WASM/non-WASM b64-extension tests to clear the new Markdown cache in addition to existing caches.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
marimo/_output/md.py	Adds a cached Markdown renderer and a lock; _md now renders via the shared renderer to reduce construction overhead and mitigate races.
tests/_output/test_md.py	Makes footnote assertions resilient to variable unique IDs and clears the new Markdown cache in WASM/non-WASM extension tests.

[cubic-dev-ai]

No issues found across 2 files

Architecture diagram

sequenceDiagram
    participant UI as marimo UI
    participant _md as _md(Html) constructor
    participant render as _render_markdown()
    participant cache as _get_markdown() singleton
    participant markdown as markdown.Markdown instance
    participant lock as threading.Lock
    participant extensions as _get_extensions()
    participant configs as _get_extension_configs()

    Note over UI,configs: Markdown rendering flow (per render call)

    UI->>_md: Instantiate _md(text)
    _md->>render: _render_markdown(text)
    
    render->>cache: _get_markdown()
    Note over cache: @functools.lru_cache singleton<br/>Returns (Markdown, Lock) tuple
    
    cache->>extensions: _get_extensions()
    extensions-->>cache: List of extensions
    cache->>configs: _get_extension_configs()
    configs-->>cache: Extension config dict
    
    alt First call (cache miss)
        cache->>markdown: markdown.Markdown(extensions, extension_configs)
        Note over markdown: Expensive construction
        cache->>lock: threading.Lock()
        cache-->>render: (markdown instance, lock)
    else Subsequent calls (cache hit)
        cache-->>render: (cached markdown, cached lock)
    end
    
    render->>lock: acquire()
    render->>markdown: reset()
    Note over markdown: Clears internal state,<br/>including footnote counter
    render->>markdown: convert(text)
    markdown-->>render: HTML string
    render->>lock: release()
    
    render-->>_md: HTML string
    _md->>_md: strip() + replace <p> with <span>
    _md-->>UI: HTML output

    Note over UI,configs: Thread safety for concurrent calls (e.g. Jedi preview)

    par Concurrent render calls
        UI->>+_md: Render text A (thread 1)
        UI->>+_md: Render text B (thread 2)
        
        _md->>render: _render_markdown(text A)
        _md->>render: _render_markdown(text B)
        
        render->>cache: _get_markdown()
        cache-->>render: same singleton
        
        alt Thread 1 acquires lock first
            render->>lock: acquire() (thread 1)
            render->>markdown: reset() + convert(text A)
            lock->>render: release()
            
            Note over markdown: Thread 2 waits here
            render->>lock: acquire() (thread 2)
            render->>markdown: reset() + convert(text B)
            lock->>render: release()
            
            render-->>_md: HTML A (thread 1)
            render-->>_md: HTML B (thread 2)
        end
    end

Loading

[kirangadhave]

🚀