Cursor Markdown Viewer: How I Read Agent Output on macOS

I run several Cursor agents at once, and by the end of a session my repo has more new markdown in it than new code: a plan file per agent, a spec, an updated AGENTS.md, a pile of review notes. All of it is written to be read, and none of it is written by me. That is the gap a Cursor markdown viewer fills. Cursor stays the place I write and run agents, and a second window handles the reading. MacMD Viewer is the one I built for that job, $19.99 one-time.

TL;DR: Cursor's markdown preview is an editing surface, not a reading surface. As of July 2026 the Preview toggle does not appear at all for *.plan.md files, files inside git worktrees, or anything under .cursor/, .claude/ or .codex/ — which is precisely where agent output lives (Cursor staff, 2026-07-18). Pair Cursor with a separate viewer rather than fighting the pane.

If your preview is outright broken right now (blank pane, Mermaid showing as plain text), fix that first with the Cursor and VS Code preview troubleshooting guide. This article is about the setup you want once it works.

What Is the Best Cursor Markdown Viewer Setup?

Keep Cursor for writing and running agents, and add a dedicated read-only viewer for reading what those agents produce. On macOS that means a native app registered as the default .md handler, with its own file watcher and a QuickLook extension, running in a second window that never writes to the file it renders.

Three things make the pairing worth the trouble, and every one of them comes from Cursor's own documentation or a Cursor staff member:

1. Cursor's product direction is what generates the markdown volume: Plan Mode, the Agents Window, AGENTS.md.
2. Cursor's preview toggle is absent exactly where that markdown lands (staff, July 2026).
3. Cursor's inline preview can re-serialize and rewrite the file it is previewing (staff, April 2026).

None of that makes Cursor bad at markdown. It makes Cursor an editor, which is what it is.

Why Does Cursor Produce So Much Markdown Now?

Because markdown became the interface between you and the agent rather than a side effect of it. Cursor's own blog puts it plainly: "Most new features at Cursor now begin with Agent writing a plan," and that plan is a markdown file with file paths and code references (Cursor, October 2025).

Cursor 3.0, released 2 April 2026, pushed it further. The Agents Window "allows you to run many agents in parallel across repos and environments: locally, in worktrees, in the cloud, and on remote SSH", and /best-of-n "runs the same task in parallel across multiple models, each in its own isolated worktree" (Cursor changelog). Parallel agents across isolated worktrees multiplies the markdown.

Then there is the instruction layer. AGENTS.md is used by more than 60,000 open-source projects and is now stewarded by the Agentic AI Foundation under the Linux Foundation, read by Cursor, Codex, Copilot, Gemini CLI, Zed and 20-odd other tools (agents.md, 2026).

The background volume predates agents. GitHub's Octoverse 2025 report puts a README in roughly 63% of public repositories, and counts 1.1 million public repos using an LLM SDK, up 178% year over year (GitHub Octoverse, 2025).

Writing markdown was always a small part of a developer's day. Reading it is now a large one, and that is a different job.

Where Cursor's Preview Toggle Doesn't Show Up

This is the detail that changed how I set up my screen. Cursor's Preview | Source switch sits in the top-right of the file header in the Agents Window, and a regular .md opens in Preview by default. But a Cursor staff moderator confirmed on 18 July 2026 that the toggle does not appear for four categories of file:

• files ending in *.plan.md, which open in a separate Plan editor with its own rich view
• files inside git worktrees
• files under .cursor/
• files under .claude/ and .codex/

Source: Cursor forum, staff reply, 2026-07-18. The staff workaround is to "Save files as regular .md files in standard workspace folders."

Read that list next to the previous section. Plan files, worktree files and agent instruction directories are not edge cases in a Cursor 3.x workflow, they are the workflow. Plans are saved to your home directory by default and only move into the repository when you click "Save to workspace" (Cursor docs). An app that renders any .md on disk, regardless of path or extension, has no version of this problem: it has no concept of a workspace folder to be outside of.

Can Cursor's Preview Rewrite Your Markdown File?

In one specific mode, yes, and Cursor staff have confirmed it. The inline preview toggle uses a WYSIWYG engine that re-serializes the markdown when you switch modes or tabs, and "the content then gets written back to disk with no warning" (Cursor staff, forum, 2026-04-08, Cursor 3.0.13).

The long-running bug report behind that reply lists what the round trip destroys: HTML comments, raw HTML elements such as page-break divs, underscore placeholder lines replaced with dashes, YAML frontmatter delimiters (--- converted into ## heading syntax), table spacing and alignment, and glob patterns, which come back wrapped in stray backticks. Staff response on that thread:

This looks like a real bug with the in-place Markdown preview toggle… When you switch back to edit mode, the WYSIWYG layer seems to re-serialize the Markdown, which strips raw HTML.

It was first reported on 4 March 2026 on v2.6.11, reconfirmed on macOS on 19 March on v2.6.19, and was still present on 8 April on v3.0.13 (Cursor forum). No fix had been announced at the time of writing.

Two takeaways, one temporary and one not. The immediate one: use the classic side-pane preview (Cmd+Shift+V) rather than the in-place toggle, which is what Cursor staff recommend. The durable one: a preview that can write is a different category of tool from a viewer that cannot. If frontmatter matters to you, and it does the moment anything in your stack parses YAML, a read-only renderer removes that failure mode by construction rather than by patch.

Does Cursor Still Use VS Code's Markdown Renderer?

No, and this is the correction that matters most if you are searching for a Cursor markdown viewer. On 3 April 2026, responding to a report on Cursor 3.0.9 (which bundles VSCode 1.105.1), a Cursor staff moderator wrote: "Cursor uses its own markdown renderer, not the native VS Code one, and it has performance issues" (Cursor forum).

The same thread has a user reporting that "the rendering is noticeably slow. It does not display immediately the way it does in VS Code", and staff attributing a startup freeze to the editorAssociations setting activating the preview renderer for every .md file at launch, which blocks the main thread. Their workaround is to remove editorAssociations and open previews manually.

Most writing about markdown in Cursor still opens with some version of "Cursor and VS Code share the same markdown preview engine." As of Cursor 3.x it is not true, and it explains why VS Code advice does not always transfer.

Can You Install Markdown Extensions in Cursor?

Yes, and it is worth stating clearly because the opposite claim gets repeated a lot. Cursor moved its in-app extension library to Open VSX in June 2025 (Cursor forum announcement), a change driven by Microsoft's marketplace terms limiting extension use to "in-scope products and services" (DevClass, April 2025).

Cursor's docs are straight about the consequence: "Most popular extensions are available on Open VSX, but not every Microsoft Marketplace extension is listed there" (Cursor docs). Both markdown previewers that matter are there. I checked the registry directly rather than trusting a summary:

Extension	Version	Published	Downloads
bierner.markdown-mermaid	1.32.1	2026-05-21	683,700
shd101wyy.markdown-preview-enhanced	0.8.30	2026-06-08	1,670,135

Source: Open VSX Registry, figures read 26 July 2026.

Mermaid does need one of them. A Cursor staff moderator confirmed on 29 December 2025, on Cursor 2.2.44, that "Mermaid is supported in Cursor, but it needs an extension", pointing to bierner's Markdown Preview Mermaid Support (Cursor forum).

So the honest case for a separate viewer is not that Cursor locks you out of extensions. It is about what the renderer does, where the preview is available at all, and whether it can modify your file.

What a Read-Only Viewer Does That a Preview Pane Can't

A preview pane is a feature of an editor. It inherits the editor's tab state, its window, its lifecycle, and in Cursor's inline mode its write path. A viewer is a separate application with none of those couplings. Concretely, for MacMD Viewer:

• Read-only by design. There is no editing surface, so no rendering path can serialize anything back into your file. That is the shape of the app, not a discipline I have to maintain.
• Its own file watcher. When an agent overwrites a plan mid-run, the open document reloads on its own. The watcher belongs to the viewer, so nothing about it depends on which process did the writing.
• Mermaid without an extension. Fenced mermaid blocks render on open, which matters because agents emit diagrams freely.
• QuickLook in Finder. Select a .md file, press Space, read it rendered. macOS ships no markdown QuickLook support at all, so something has to fill the gap. Free options exist, including QLMarkdown; MacMD's is the one that matches the rest of the viewer.
• Twelve document themes, syntax highlighting and native SwiftUI rendering, in a 5.4 MB download.

The tradeoff is real and I would rather name it than bury it: you cannot fix a typo in MacMD Viewer. You switch to Cursor, fix it there, and the viewer reloads. If what you want is one window that does both jobs, this is the wrong tool and Cursor's side-pane preview is the right one.

MacMD Viewer: native Markdown viewer for Mac with Mermaid diagrams and QuickLook. $19.99 one-time purchase →

My Cursor and MacMD Viewer Setup on macOS

Cursor takes the left two-thirds of the screen and MacMD Viewer the right third. MacMD is registered as the default handler for .md, so anything I double-click in Finder or open from the terminal arrives rendered instead of as an editor tab I then have to close.

For files an agent has just written, I usually stay in Finder: select the file, press Space, read, move on. That covers worktree scratch files and anything under .claude/ or .codex/, which the preview toggle skips entirely.

The rule I settled on is boring and it holds up: if I intend to change a file, I open it in Cursor; if I intend to read it, I open it anywhere else. The same split applies to markdown pasted out of a chat window rather than written by an agent, which saving ChatGPT or Claude output as markdown on Mac covers. If MacMD is not the right fit, the Mac markdown app roundup walks through the alternatives.

Frequently Asked Questions

What is the best markdown viewer to use with Cursor on Mac?

Keep Cursor for writing and running agents, and add a dedicated read-only viewer for reading their output. A native macOS app registered as the default .md handler, with its own file watcher and a QuickLook extension, renders any file on disk regardless of path — including the plan files and worktree files Cursor's own preview toggle skips. MacMD Viewer is $19.99 one-time.

Does Cursor render Mermaid diagrams in markdown?

Not on its own. A Cursor staff moderator confirmed on 2025-12-29 (Cursor 2.2.44) that Mermaid is supported but needs an extension, recommending Markdown Preview Mermaid Support by bierner. It is available on Open VSX, which is where Cursor's extension library now points. A viewer with built-in Mermaid rendering skips the install.

Why is there no Preview toggle for my .plan.md file in Cursor?

By design, as of 2026-07-18. Cursor staff confirmed the Preview | Source switch does not appear for files ending in *.plan.md, files inside git worktrees, or files under .cursor/, .claude/ and .codex/. Plan files get their own Plan editor with a rich view; worktree and agent-directory files get no rendered view from the toggle at all. The staff workaround is to save files as regular .md files in standard workspace folders.

Can Cursor's markdown preview modify my file?

The inline preview toggle can. Cursor staff confirmed in April 2026 (v3.0.13) that its WYSIWYG engine re-serializes markdown when you switch modes or tabs and writes the result back to disk with no warning, stripping raw HTML and mangling YAML frontmatter delimiters. Staff recommend the classic side-pane preview (Cmd+Shift+V) instead.

Does Cursor use the same markdown renderer as VS Code?

No, not since Cursor 3.x. A Cursor staff moderator stated on 2026-04-03, on Cursor 3.0.9, that Cursor uses its own markdown renderer rather than the native VS Code one, and that it has performance issues. Markdown preview advice written for VS Code does not reliably transfer to current Cursor.

Can I install markdown extensions in Cursor?

Yes. Cursor moved its extension library to Open VSX in June 2025. Both major markdown previewers are published there: bierner.markdown-mermaid (v1.32.1, 683,700 downloads) and shd101wyy.markdown-preview-enhanced (v0.8.30, 1,670,135 downloads). The case for a separate viewer is renderer behaviour and file safety, not extension availability.