Markdown Preview in VS Code: Shortcut, Mermaid & Fixes

TL;DR: VS Code has a built-in Markdown preview — press Cmd+Shift+V (no extension needed). Add Markdown All in One for keyboard shortcuts and table formatting, markdownlint for linting, and Markdown Preview Enhanced for PDF, HTML and PNG export. Math (KaTeX) renders in the built-in preview since VS Code 1.58, and custom CSS works through the markdown.styles setting. Mermaid diagrams render in the built-in preview since VS Code 1.121 (May 2026). For pure reading without the editor UI, MacMD Viewer ($19.99, one-time) opens .md files natively with a double-click.

VS Code is the most popular code editor on the planet, and it handles Markdown reasonably well right out of the box. The built-in preview covers the basics, and a small set of extensions elevates it into a capable Markdown writing environment. This guide covers everything from the zero-configuration starting point through extensions, keyboard shortcuts, and settings — plus where VS Code's Markdown support stops and a dedicated viewer picks up.

Does VS Code Support Markdown Out of the Box?#

Yes. VS Code ships with a CommonMark-compatible Markdown renderer and a live preview panel — no extension installation required, as documented in the official VS Code Markdown docs. Open any .md file and you have two preview options:

• Cmd+Shift+V — opens the preview in a new tab
• Cmd+K V — opens the preview in a split panel to the right of the editor

The split-panel view (Cmd+K V) is the more practical choice for writing. Your source is on the left, the rendered output updates on the right as you type. The renderer handles all standard Markdown syntax: headings, bold, italic, code blocks, tables, blockquotes, and links. GitHub Flavored Markdown (GFM) extensions like strikethrough and task lists are also supported.

The Outline panel gives you a navigable heading hierarchy for any open Markdown file. Enable it via View > Open View > Outline. Every heading in your document appears as a collapsible tree — click any entry to jump directly to that section. This is particularly useful for long README files or documentation where scrolling is slow.

How Do You Make VS Code Open Markdown Files in Preview by Default?#

Add one setting to settings.json and every .md file opens as the rendered preview instead of the source. Open the Command Palette (Cmd+Shift+P), run "Preferences: Open User Settings (JSON)" and add:

"workbench.editorAssociations": {
  "*.md": "vscode.markdown.preview.editor"
}

The official VS Code Markdown docs say this applies to files opened from the Explorer and to Markdown diffs from Source Control. If you review changes and want diffs in the text editor, also set "workbench.diffEditorAssociations": { "*.md": "default" }, which takes precedence for diff views.

To get the source back for one file, run View: Reopen Editor With... from the Command Palette and pick the text editor.

If you write more than you read, keep the source on screen instead. With Markdown All in One installed, set "markdown.extension.preview.autoShowPreviewToSide": true and the preview opens beside every Markdown file you open. Preview only for reading, preview to the side for writing.

Two limits. The default preview is still the built-in one, so Mermaid blocks render only on VS Code 1.121 or later, or with an extension on older versions (see the Mermaid section below). And in Cursor, staff tied a startup freeze to this same setting opening the preview renderer for every .md file at launch — the Cursor Markdown viewer setup guide has the details.

Even as the default, the preview lives inside the editor window. If you only want to read, the other route is a dedicated viewer set as the default app for .md files in Finder — see how to open .md files on Mac.

What Extensions Are Worth Installing?#

The built-in preview covers reading. For writing, three extensions make a meaningful difference.

Markdown All in One#

Extension ID: yzhang.markdown-all-in-one

This is the single most impactful Markdown extension in the VS Code marketplace. It adds:

• Keyboard shortcuts — Cmd+B for bold, Cmd+I for italic, without needing to manually wrap text in asterisks
• Table of contents generator — run "Create Table of Contents" from the command palette; it auto-updates on save
• Table formatter — Alt+Shift+F aligns all pipe separators in a Markdown table automatically
• List editing improvements — pressing Enter inside a list item continues the list; Tab indents, Shift+Tab de-dents
• Auto-completion — file paths for image and link references

If you only install one Markdown extension, make it this one.

markdownlint#

Extension ID: DavidAnson.vscode-markdownlint

markdownlint enforces the MD rule set and underlines violations directly in the editor. Common rules it catches:

• MD009 — trailing spaces
• MD010 — hard tabs instead of spaces
• MD012 — multiple consecutive blank lines
• MD022 — headings not surrounded by blank lines
• MD041 — first line of file is not a top-level heading

You can configure which rules apply by adding a .markdownlint.json file to your project root. It integrates with VS Code's Problems panel so all lint errors appear alongside TypeScript and ESLint warnings.

Markdown Preview Enhanced#

Extension ID: shd101wyy.markdown-preview-enhanced

The built-in VS Code preview already renders math equations with KaTeX (since VS Code 1.58, June 2021; turn it off with "markdown.math.enabled": false) and accepts custom CSS through the markdown.styles setting. Markdown Preview Enhanced goes further with export options: PDF, HTML, and PNG from a right-click context menu, plus its own extended Markdown features.

It renders Mermaid too, though since VS Code 1.121 (May 2026) the built-in preview does as well, with no extension. Write a fenced code block with the mermaid language tag and it renders inline. See our Mermaid live editor guide for the full diagram syntax — the same code works here. If you are curious about how diagrams render in dedicated viewers, the Mermaid diagram viewer guide covers the differences between rendering environments.

Paste Image#

Extension ID: mushan.vscode-paste-image

If you write documentation with screenshots, Paste Image lets you paste an image directly from the clipboard (Cmd+Alt+V) and automatically saves the file to your project and inserts the correct Markdown image reference. Small quality-of-life improvement that saves repetitive manual steps.

What Are the Essential Keyboard Shortcuts?#

The table below covers shortcuts available after installing Markdown All in One. The preview shortcuts are built-in — no extension needed.

The Cmd+B and Cmd+I shortcuts from Markdown All in One wrap selected text in ** and _ respectively — or remove the markers if the text is already formatted. This mirrors the behavior of rich-text editors and makes inline text formatting faster.

How Do You Configure VS Code for Markdown Files?#

VS Code supports language-specific settings, which means you can apply different editor behavior to .md files without affecting your code files. Add these to your settings.json (Cmd+Shift+P → "Open User Settings JSON"):

{
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
      "other": "on",
      "comments": "off",
      "strings": "off"
    },
    "editor.defaultFormatter": "yzhang.markdown-all-in-one"
  },
  "markdown.preview.fontSize": 16,
  "markdown.preview.lineHeight": 1.6
}

Word wrap (editor.wordWrap: "on") is the most important setting for Markdown. Long prose lines scroll horizontally without it, which makes writing uncomfortable. Word wrap keeps the full line visible at any window width.

Quick suggestions for Markdown files surfaces file path completions as you type links and image references — useful for keeping relative paths correct in documentation projects.

Preview font size and line height control the built-in preview panel's typography. The defaults (14px, 1.4) are optimized for code, not prose. Bumping to 16px/1.6 makes the preview more readable for longer documents.

Snippets#

VS Code includes built-in Markdown snippets that expand with Tab. Type the trigger word inside a .md file, press Tab, and VS Code expands it:

You can also define your own snippets (Cmd+Shift+P → "Snippets: Configure Snippets" → markdown). This is useful for frequently used structures like frontmatter templates, table skeletons, or custom callout blocks.

Does VS Code Support Mermaid Diagrams in Markdown?#

Yes, since VS Code 1.121 (May 2026). Matt Bierner's Markdown Preview Mermaid Support extension now ships inside VS Code as the built-in Mermaid Markdown Features extension, so the built-in preview (Cmd+Shift+V) renders Mermaid fenced code blocks with nothing to install (VS Code 1.121 release notes).

On older VS Code versions the built-in preview shows Mermaid blocks as plain code. Update VS Code, or install Markdown Preview Mermaid Support (bierner.markdown-mermaid) and reload the window. In Cursor, a VS Code fork on its own release cadence, install the same extension if diagrams show as plain text. A block like this renders as a diagram:

```mermaid
flowchart LR
    A[Write Markdown] --> B[Preview in VS Code]
    B --> C{Looks good?}
    C -->|Yes| D[Commit]
    C -->|No| A
```

The Mermaid flowchart guide covers the full syntax for nodes, edges, and subgraphs. Everything that works in the live editor works here.

What Are the Limitations of VS Code's Markdown Preview?#

If you're hitting a specific bug — blank preview, Mermaid not rendering, stale content after a Cursor agent edits the file — see our Cursor and VS Code preview troubleshooting guide for the common fixes.

VS Code's built-in preview is solid for basic Markdown but has meaningful gaps:

Mermaid only on recent versions. Diagrams render in the built-in preview since VS Code 1.121 (May 2026); older versions need the Markdown Preview Mermaid Support extension.

No footnotes in the built-in renderer. The footnote syntax ([^1]) is not rendered. You need Markdown Preview Enhanced for footnotes.

Task list checkboxes are not interactive. GFM task lists render visually as checkboxes, but clicking them does nothing in the preview. They are display-only.

Custom CSS requires a setting. The built-in preview uses VS Code's theme colors by default. To restyle it, list your stylesheets in the markdown.styles setting; no extension is needed.

It is a side panel, not a viewer. The preview exists inside VS Code. Double-click a .md file in Finder and it opens in the editor unless you set the preview as default (see above) — and either way the whole editor window comes with it.

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

When Should You Use MacMD Viewer Instead of VS Code?#

VS Code is the right tool when you are editing Markdown. You write, run code, commit to git — the preview panel is a companion to your workflow.

MacMD Viewer is the right tool when you want to read a Markdown file. The difference is meaningful in practice:

• Double-click any .md file in Finder — MacMD Viewer ($19.99, one-time) opens it instantly, rendered, no editor chrome
• No setup required — register it as the default .md handler once and every Markdown file on your Mac opens with a full preview
• Native macOS feel — the app is built with SwiftUI, respects your system appearance (light/dark), and feels like a first-class macOS document viewer
• Finder Quick Look and live reload — press Space on a .md file in Finder to see it rendered, Mermaid included, and an open document reloads when an editor or coding agent saves it

The analogy: VS Code is a word processor. MacMD Viewer is a PDF viewer. You edit .docx in Word and read .pdf in Preview. For Markdown, VS Code handles editing, MacMD Viewer handles viewing — and at $19.99 one-time with no subscription, the cost comes down to a single cup of coffee.

If you frequently open README files, documentation, or notes from Finder and just want to read them rendered — without the overhead of a full editor — see MacMD Viewer pricing ($19.99, one-time). For more on how to view .md files on macOS in general, the how to view Markdown files guide, the Markdown QuickLook guide for Mac, and our review of native Markdown viewers for macOS cover the full set of options — and if you're weighing VS Code against dedicated apps, the best Markdown viewer roundup ranks them side by side.

Frequently Asked Questions#

How do you preview Markdown in VS Code?#

Press Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows/Linux) with a .md file open. This opens a rendered preview in a new tab. For a split-panel view that updates as you type, press Cmd+K V instead. No extension is needed — VS Code includes a CommonMark renderer by default.

How do you make VS Code open Markdown files in preview by default?#

Add "workbench.editorAssociations": { "*.md": "vscode.markdown.preview.editor" } to your settings.json. Every .md file then opens as the rendered preview. Run View: Reopen Editor With... from the Command Palette to switch a file back to the source.

What is the best VS Code extension for Markdown?#

Markdown All in One (yzhang.markdown-all-in-one) is the most useful single extension. It adds Cmd+B/Cmd+I shortcuts for bold and italic, a table formatter (Alt+Shift+F), an auto-updating table of contents, and better list editing behavior. Pair it with markdownlint (DavidAnson.vscode-markdownlint) for syntax validation.

Does VS Code support Mermaid diagrams in Markdown?#

Yes, since VS Code 1.121 (May 2026): Mermaid fenced code blocks render as diagrams in the built-in preview with no extension. On older versions, install Markdown Preview Mermaid Support (bierner.markdown-mermaid) and reload the window. The same diagrams that work in the Mermaid live editor work here.

How do you format a Markdown table in VS Code?#

Install Markdown All in One, place your cursor anywhere inside a Markdown table, and press Option+Shift+F (Mac) or Alt+Shift+F (Windows). The extension aligns all column separators to produce a clean, readable table in the source.

What is the difference between VS Code and MacMD Viewer for Markdown?#

VS Code is a code editor with a Markdown preview panel — the right tool for writing and editing .md files. MacMD Viewer ($19.99, one-time) is a dedicated native macOS viewer that registers as the default .md file handler. Double-clicking any Markdown file in Finder opens it in MacMD Viewer, fully rendered, with no editor interface. Different tools for different jobs: edit in VS Code, read in MacMD Viewer.