Cursor and VS Code Markdown Preview Not Working — Fixes and a Mac Alternative

Cursor and VS Code share the same Markdown preview engine. They also share the same set of well-documented preview problems: blank panes after window resize, Mermaid not rendering, stale previews after agent file edits, themes that fight back. The fixes below cover the common cases, then a section on when to stop fighting the preview pane and switch to a dedicated Mac viewer.

Key Takeaways

• VS Code's built-in Markdown preview does not support Mermaid — install Markdown Preview Mermaid Support or use a Mermaid-native viewer.
• Cursor's preview pane often goes stale after agent file edits because the agent's write path doesn't trigger the preview's file watcher reliably.
• A dedicated viewer like MacMD Viewer renders Markdown + Mermaid natively, watches files, and survives editor session resets — $19.99 one-time.

What Are the Common Cursor and VS Code Preview Problems?

Cursor inherits VS Code's Markdown preview as well as its bugs. The five issues below cover roughly 90% of "preview not working" reports across GitHub issues and Cursor forum threads.

1. Preview pane is blank or stuck on old content. Symptom: open a .md file, hit Cmd+K V, and the preview shows nothing — or shows the previously-open file. Cause: stuck preview state.
2. Mermaid code fences render as plain text. Symptom: ```mermaid blocks appear as code, not diagrams. Cause: VS Code's built-in preview has no Mermaid renderer.
3. Preview pane goes stale after an agent edits the file. Symptom: Cursor's agent rewrites a .md, but the preview still shows the old content. Cause: the agent's write path doesn't always fire the preview's file-change watcher.
4. Themes look broken in preview. Symptom: preview uses different colors than the editor, or fonts look wrong. Cause: VS Code preview CSS doesn't always inherit the workspace theme correctly.
5. Preview is slow on large files. Symptom: Markdown files over ~3,000 lines lag during scroll. Cause: full re-render on each scroll position update.

Cursor and VS Code's preview pane is built for one job: showing what you wrote. It struggles when an external process (agent, file watcher, save from another app) modifies the file mid-session (VS Code Markdown Preview issues, 2024-2026).

How Do I Fix VS Code Markdown Preview That's Blank or Stuck?

The fix path is reliable: reload the editor, then verify extensions. 90% of blank-preview reports clear after a window reload.

Step 1: Reload the Window

Open the command palette (Cmd+Shift+P), run Developer: Reload Window. This restarts VS Code's renderer without closing your project. If the preview comes back, the issue was stuck state — note when it happens (usually after long sessions or theme switches) and consider a viewer that doesn't share editor session state.

Step 2: Disable Conflicting Extensions

Common conflicts: multiple Markdown extensions installed (e.g., Markdown All in One + Markdown Preview Enhanced + custom theme plugins). Disable extensions one by one with Cmd+Shift+P → Extensions: Disable, reloading between each.

Step 3: Open in a New Tab

If a specific file always shows blank, close the file and reopen in a new tab. VS Code occasionally loses the language-mode association.

Step 4: Toggle the File Watcher Setting

Open settings (Cmd+,) and search files.useExperimentalFileWatcher. Toggle the setting and reload. Some users report the experimental watcher fixes Cursor's agent-edit reload bug; others see the opposite. Test both.

How Do I Render Mermaid in VS Code or Cursor?

Install the free Markdown Preview Mermaid Support extension from Matt Bierner. The extension hooks into VS Code's built-in preview and renders Mermaid code fences inline. Available from the VS Code marketplace. Works in Cursor without modification — Cursor extensions are VS Code-compatible.

After install, reload the window (Cmd+Shift+P → Developer: Reload Window). Mermaid blocks in your preview should now render as diagrams. If they still show as plain text, an older Markdown preview extension is intercepting first — disable other Markdown preview extensions and reload.

For Mermaid coming out of AI agents (which is the most common 2026 source — Claude, Cursor agents, and ChatGPT all emit Mermaid liberally), a Mermaid-native viewer like MacMD Viewer skips the extension dance. For deeper Mermaid usage see our Mermaid Live Editor guide.

Why Does Cursor's Preview Go Stale After Agent File Edits?

Cursor agents write to files through their own pathway, which doesn't always trigger the preview pane's file watcher. The result: the agent finishes, you click the preview pane, and it still shows the pre-edit content. You have to manually close and reopen the preview to get the new render.

The mechanics: VS Code's Markdown preview uses a file-change subscription to refresh. Most file-system writes (Cmd+S, external editors, git checkout) fire this event. Some Cursor agent writes don't — observed in user reports across the Cursor forum.

Workarounds

• Close and reopen the preview (Cmd+W on the preview tab, then Cmd+K V on the file).
• Switch tabs and switch back — sometimes the preview re-reads the file on focus.
• Save the file manually with Cmd+S after the agent finishes — this usually triggers the watcher.
• Use a separate viewer that watches the file independently.

Cursor agents writing to .md files can leave the preview pane on stale content because the agent's write path doesn't always fire VS Code's file watcher. A dedicated viewer with its own watcher (refresh ~50 ms) sidesteps the bug entirely.

When Should You Switch to a Dedicated Mac Markdown Viewer?

If you spend more than five minutes a day fighting the preview pane, the answer is now. A dedicated viewer is the right shape when:

• You read Markdown more often than you edit it (agent output, READMEs, shared docs).
• You need reliable Mermaid rendering without managing extensions.
• You want preview that survives reopening the editor.
• You want QuickLook hover-preview in Finder (only a native macOS app can register as a QuickLook provider).

MacMD Viewer is the native option: SwiftUI, 2 MB, $19.99 one-time. It renders Markdown plus Mermaid natively, watches the open file for live reload, integrates with QuickLook, and runs as a separate window so it doesn't follow your editor's tab state. Pair it with Cursor or VS Code — Cursor on the left half of your screen for editing, MacMD on the right for reading. For a broader landscape of Mac Markdown options, see our Markdown apps for Mac roundup.

When the Built-In Preview Is Still Fine

If you only open .md files occasionally, the built-in preview plus the Mermaid extension is acceptable. The case for a dedicated viewer is volume: if AI agents are emitting Markdown into your project all day, you'll feel the difference. For more on that workflow specifically see our AI Markdown output on Mac guide.

What's the Right Long-Term Setup for Mac Markdown Workflows?

Use Cursor or VS Code as your editor. Use a viewer for reading. Don't try to make one tool do both jobs well.

Use case	Tool
Writing or editing Markdown	Cursor or VS Code
Running AI agents that write .md	Cursor (agents) or Claude Code (CLI)
Reading rendered output (agent docs, READMEs)	MacMD Viewer
Quick Finder preview	MacMD Viewer's QuickLook extension
Building a personal knowledge graph	Obsidian (see our Obsidian alternative on Mac)
Final review of docs before sharing	MacMD Viewer with watch mode

The two-app setup eliminates most preview-pane frustration. The editor handles writing; the viewer handles reading. Neither is overloaded.

FAQ

Why is my VS Code Markdown preview blank?

Usually a conflicting extension or a stuck preview state. Run Developer: Reload Window from the command palette (Cmd+Shift+P) — that fixes blank previews most of the time. If a recently installed Markdown extension causes it, disable extensions one by one and reload between each.

Does VS Code render Mermaid diagrams natively?

No. VS Code's built-in Markdown preview shows Mermaid code fences as plain text. Install Markdown Preview Mermaid Support (free extension by Matt Bierner) to render diagrams. Cursor inherits the same gap and the same fix — Cursor extensions are VS Code-compatible.

Why does Cursor's preview pane go stale after the agent edits a file?

Cursor agents write to files via their own pathway, which doesn't always trigger the preview pane's file watcher. Reopen the file in a new tab, or close and reopen the preview, or use a dedicated viewer that watches files independently and refreshes within milliseconds.

What's a Markdown preview that just works on Mac?

A dedicated native viewer like MacMD Viewer. Renders Markdown plus Mermaid natively (no extension), watches files for live reload (~50 ms), and integrates with QuickLook for Finder previews. It is a viewer, not an editor — keep using Cursor or VS Code for writing.

Can I open Markdown preview in a separate window from Cursor?

Yes via the command Markdown: Open Preview to the Side (Cmd+K V). For a separate dedicated window, a native viewer is more reliable — Cursor's preview lives inside the editor and follows its tab state. A separate viewer survives reopening the editor.

How do I fix Mermaid not rendering in VS Code Markdown preview?

Install Markdown Preview Mermaid Support from the marketplace, then reload the window (Cmd+Shift+P → Developer: Reload Window). For Mermaid that comes from AI agents (Claude, Cursor) which is the most common 2026 source, a Mermaid-native viewer skips the extension dance entirely.

Conclusion

Cursor and VS Code's preview pane works fine when you write Markdown by hand. It struggles when external processes — AI agents, file watchers, theme switches — modify state outside its expected path. The fixes above cover the common cases. The right long-term answer is to stop trying to make one app do both editing and reading well.

• Editor for writing. Cursor or VS Code.
• Viewer for reading. A dedicated native app that renders Mermaid, watches files, and survives editor sessions.
• Two windows, two jobs. Cursor on the left for editing and agents, MacMD Viewer on the right for reading. The editor doesn't need a preview pane open.

If preview problems eat your time daily, grab MacMD Viewer from the pricing page — 2 MB, native, Mermaid + QuickLook, $19.99 one-time. For the full Mac Markdown app landscape see our roundup.