Skip to main content

VS Code Markdown Preview

How to preview Markdown in Visual Studio Code: the shortcuts, what the built-in preview renders, the settings worth changing, and the extensions that fill the gaps.

Short answer

Open a .md file and press Ctrl+Shift+V (Cmd+Shift+V on macOS) to switch the tab to the rendered preview, or Ctrl+K V (Cmd+K V) to open it beside the editor. It updates as you type. The built-in preview renders CommonMark plus tables, strikethrough, math, and Mermaid diagrams; GitHub-only syntax such as task lists, alerts, and footnotes needs an extension.

Toggle preview

Ctrl+Shift+V / Cmd+Shift+V

Swaps the current tab between source and preview. Press it again to go back.

Open to the side

Ctrl+K V / Cmd+K V

Press Ctrl+K, let go, then press V. Source and preview stay side by side.

Opening the Preview

VS Code treats .md and .markdown files as Markdown (plus rarer extensions like .mkd and .mdown). .mdx is not on that list; MDX needs its own extension. With a Markdown file active, any of these opens the preview:

  • Ctrl+Shift+V / Cmd+Shift+V toggles the current tab between source and preview. Older VS Code releases opened the preview as a separate tab instead.
  • Ctrl+K V / Cmd+K V opens the preview in a split to the right.
  • The Open Preview to the Side button (a split pane with a magnifying glass) in the editor's top-right toolbar does the same. Alt+click it to open the preview in the current group. The Open as Preview button next to it swaps the tab in place.
  • The Command Palette (Ctrl+Shift+P): type Markdown: Open Preview.

The side preview re-renders as you type and scrolls with the editor in both directions. It follows whichever Markdown file is active; run Markdown: Toggle Preview Locking to pin it to one file.

Open Markdown in preview by default

There is no command-line flag for the preview, but this setting makes every .md file open rendered, including code README.md from a terminal. It also renders Markdown diffs from Source Control as a preview. Use View: Reopen Editor With... to get the text back for one tab.

// settings.json
"workbench.editorAssociations": {
  "*.md": "vscode.markdown.preview.editor"
}
New in 2026: VS Code 1.131 (July 2026) added an experimental Markdown Editor that shows the rendered document and lets you edit it in place. Open it with View: Reopen Editor With... > Markdown Editor. It is separate from the preview described on this page.

What the Preview Looks Like

The left side is raw Markdown. The right side is roughly what VS Code's built-in preview renders (VS Code applies your theme's colors):

# Project README

## Features
- **Fast** builds with Turbopack
- Live Markdown preview
- ~~Legacy mode~~

## Usage
Run `npm run dev` and open <http://localhost:3000>.

| Task  | Command         |
|-------|-----------------|
| Dev   | `npm run dev`   |
| Build | `npm run build` |
VS Code preview

Keyboard Shortcuts

VS Code's default bindings for Markdown work. Two-part shortcuts like Ctrl+K V are chords: press the first combination, release, then press the second key. VS Code has no built-in bold or italic shortcut for Markdown; that comes from Markdown All in One.

VS Code Markdown keyboard shortcuts
ActionWindows / LinuxmacOS
Toggle preview in the same tabCtrl+Shift+VCmd+Shift+V
Open preview to the sideCtrl+K VCmd+K V
Command PaletteCtrl+Shift+P or F1Cmd+Shift+P or F1
Go to a heading in this fileCtrl+Shift+OCmd+Shift+O
Go to a heading in any fileCtrl+TCmd+T
Suggest paths, headings, snippetsCtrl+SpaceCtrl+Space
Rename a heading and update linksF2F2
Find all links to a heading or fileShift+Alt+F12Shift+Option+F12
Expand / shrink selectionShift+Alt+Right / LeftCtrl+Shift+Cmd+Right / Left
Open SettingsCtrl+,Cmd+,
Zen modeCtrl+K ZCmd+K Z

Links, Paths, and Images

VS Code completes paths and headings inside link and image syntax. Suggestions appear when you type /, or press Ctrl+Space:

What VS Code suggests inside Markdown links
Type thisVS Code suggests
![Diagram](./Files relative to the current Markdown file
[Setup](/Files from the workspace root
[Install](#Headings in the current file
[API](##Headings in every Markdown file in the workspace; inserts the full path
  • Insert images: paste an image, or hold Shift while dragging a file into the editor. Images from outside the workspace are copied in; set markdown.copyFiles.destination to choose the folder. The commands Markdown: Insert Image from Workspace and Insert Link to File in Workspace do it from the keyboard.
  • Paste a URL over selected text to turn it into a link.
  • Rename a heading with F2 and every link to it updates, across files. Shift+Alt+F12 lists every link pointing at a heading or file.
  • Link validation is off by default. Turn on markdown.validate.enabled to get warnings for links to missing files and headings (local links only; external URLs are not checked).
  • Moving files: set markdown.updateLinksOnFileMove.enabled to prompt or always and links are rewritten when you move or rename a Markdown file, image, or folder.

Settings That Matter

Search for these in Settings (Ctrl+, or Cmd+,) under Extensions > Markdown Language Features, or add them to settings.json. Defaults are as of VS Code 1.141 (October 2026).

VS Code Markdown settings and defaults
SettingDefaultWhat it does
markdown.preview.breaksfalsetrue turns every newline into a line break, like a GitHub comment
markdown.preview.fontFamily / fontSize / lineHeightsystem font / 14 / 1.6Preview typography
markdown.styles[]Extra CSS for the preview: https URLs or paths relative to the workspace folder
markdown.preview.frontMattertableShow YAML front matter as a table, a codeBlock, or hide it
markdown.math.enabledtrueKaTeX math rendering in the preview
markdown.preview.linkifytrueTurn bare URLs into links
markdown.preview.scrollPreviewWithEditortrueScroll sync from editor to preview (scrollEditorWithPreview is the reverse)
markdown.preview.doubleClickToSwitchToEditorfalseDouble-click the preview to jump to the source (off since 1.120)
markdown.validate.enabledfalseFlag links to missing files, headings, and reference definitions
markdown.updateLinksOnFileMove.enabledneverprompt or always rewrites links when a file is moved or renamed
markdown.suggest.paths.enabledtruePath and heading completions inside links
markdown.editor.pasteUrlAsFormattedLink.enabledsmartWithSelectionPaste a URL over selected text to make a link
markdown.editor.filePaste.enabled / drop.enabledsmartPaste or Shift-drop a file to insert a link or image
markdown.copyFiles.destination(unset)Where pasted or dropped images are copied in the workspace

A sensible starting point

// settings.json
{
  // Warn about links to missing files and headings
  "markdown.validate.enabled": true,
  // Offer to fix links when you move or rename a file
  "markdown.updateLinksOnFileMove.enabled": "prompt",
  // Keep the two trailing spaces that make a hard line break
  "[markdown]": {
    "files.trimTrailingWhitespace": false
  }
}

What the Built-in Preview Renders

VS Code renders Markdown with markdown-it and targets CommonMark. Its docs say plainly that it does not support GitHub Flavored Markdown, though tables and strikethrough work, and math and Mermaid are built in. Everything GitHub-specific needs an extension; see the GitHub Markdown guide for what GitHub itself renders.

Markdown features in VS Code's built-in preview
FeatureBuilt in?Notes
Headings, bold, italic, links, lists, quotesYesStandard CommonMark
TablesYesGFM pipe tables with alignment
StrikethroughYes~~text~~
Fenced code with highlightingYeshighlight.js, by language identifier
Math ($...$ and $$...$$)YesBuilt in with KaTeX; turn off with markdown.math.enabled
Mermaid diagramsYesBuilt in since 1.121 (May 2026); before that, an extension
YAML front matterYesShown as a table by default since 1.121
Raw HTMLYesPassed through; scripts are blocked by the preview's security level
Bare URL autolinksYesmarkdown.preview.linkify
Single newline as a line breakNoOff by default; set markdown.preview.breaks
Task lists - [ ]ExtensionMarkdown Checkboxes, or Markdown All in One
GitHub alerts > [!NOTE]ExtensionMarkdown All in One
Footnotes [^1]ExtensionMarkdown Footnotes
Emoji :shortcodes:ExtensionMarkdown Emoji
Wikilinks [[...]]ExtensionFoam or another notes extension
PlantUML, Graphviz, code chunksExtensionMarkdown Preview Enhanced
Export to PDF or HTMLExtensionMarkdown PDF, or Markdown All in One (HTML)

If you installed Markdown Preview Mermaid Support before 1.121, VS Code now ships the same code as the built-in Mermaid Markdown Features extension, so the separate install is no longer needed.

Extensions Worth Installing

Most people need at most two: Markdown All in One for editing and markdownlint for consistency. Search the Extensions view (Ctrl+Shift+X) for the ID to get the right one.

Markdown All in One

yzhang.markdown-all-in-one

Editing shortcuts (Ctrl/Cmd+B bold, Ctrl/Cmd+I italic, Ctrl+Shift+] and [ for heading level, Alt+C to tick a task on Windows/Linux), list continuation on Enter, a Create Table of Contents command that updates on save, Print to HTML, and task lists, GitHub alerts, and math in the built-in preview.

markdownlint

DavidAnson.vscode-markdownlint

Underlines style problems (MD001-style rules) as you type, with Ctrl+. quick fixes. Every rule is on except MD013 line length. Configure it with a .markdownlint.json file; the old markdownlint.config setting is deprecated.

Markdown Preview Enhanced

shd101wyy.markdown-preview-enhanced

A separate, heavier preview with PlantUML, Graphviz, runnable code chunks, and Pandoc, PDF, and ebook export. It binds Ctrl+Shift+V and Ctrl+K V to its own preview.

GitHub Markdown Preview (extension pack)

bierner.github-markdown-preview

Matt Bierner's pack of four small extensions: Markdown Preview Github Styling (GitHub's look, styling only), plus Markdown Checkboxes, Markdown Emoji, and Markdown Footnotes, which add task lists, :emoji: shortcodes, and footnotes to the built-in preview. Each can be installed on its own.

Markdown PDF

yzane.markdown-pdf

Exports the current file to PDF, HTML, PNG, or JPEG. It uses your installed Chrome, Edge, or Chromium, or downloads a copy on first use.

Fix markdownlint problems on save

// settings.json
"editor.codeActionsOnSave": {
  "source.fixAll.markdownlint": "explicit"
}

Common Mistakes

The problems behind most “my preview looks wrong” questions.

Does not work

Line one
Line two

Use instead

Line one\
Line two
VS Code follows CommonMark, so a single newline is a space and both lines run together. End the line with a backslash or two spaces, or set markdown.preview.breaks to true if you want GitHub-comment behavior.

Does not work

Line one··
Line two

Use instead

"[markdown]": {
  "files.trimTrailingWhitespace": false
}
If files.trimTrailingWhitespace is on, saving deletes the two trailing spaces (shown as ··) that make a hard break. Turn it off for Markdown only, or use a trailing backslash, which survives trimming.

Does not work

![Chart](http://example.com/chart.png)

Use instead

![Chart](https://example.com/chart.png)
The preview's default Strict security blocks images loaded over http. Use https, or change it with Markdown: Change Preview Security Settings if you trust the workspace.

Does not work

- [ ] Write docs
- [x] Ship it

Use instead

Install Markdown Checkboxes
or Markdown All in One
Task lists are GitHub syntax that the built-in preview does not render: you get bullets with a literal [ ] and [x]. An extension adds the checkboxes.

Does not work

> [!WARNING]
> Watch out

Use instead

> **Warning**
> Watch out
GitHub alerts render as a plain blockquote in the built-in preview. Use bold text, or install Markdown All in One, which adds GitHub-style alerts to the preview.

Does not work

| Name | Role |
| Alice | Developer |

Use instead

| Name  | Role      |
|-------|-----------|
| Alice | Developer |
A table needs the separator row (|---|---|) under the header. Without it the preview shows the pipes as plain text.

Does not work

[[Related Note]]

Use instead

[Related Note](../notes/related.md)
Wikilinks are Obsidian syntax. VS Code's preview does not recognize [[...]] unless you install a notes extension such as Foam.

Frequently Asked Questions

How do I preview Markdown in VS Code?

Open a .md file and press Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. That toggles the current tab between the source and the rendered preview. To keep the source open and see the preview next to it, press Ctrl+K, release, then V (Cmd+K V on macOS).

How do I open the Markdown preview side by side?

Press Ctrl+K V (Cmd+K V on macOS), click the Open Preview to the Side button in the editor's top-right toolbar, or run Markdown: Open Preview to the Side from the Command Palette. The preview updates as you type, scrolls with the editor, and follows whichever Markdown file is active unless you lock it with Markdown: Toggle Preview Locking.

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

Add "workbench.editorAssociations": { "*.md": "vscode.markdown.preview.editor" } to your settings.json. Markdown files then open rendered, including from the Explorer or with code README.md in a terminal, and Ctrl+Shift+V or Reopen Editor With switches an individual tab back to text.

Why does my Markdown look different in VS Code than on GitHub?

They use different renderers. VS Code's preview uses markdown-it and targets CommonMark; its own docs say it does not support GitHub Flavored Markdown. It does render tables, strikethrough, math, and Mermaid, but GitHub-only syntax such as task lists, alerts, footnotes, emoji shortcodes, and #123 issue links needs extensions. Line breaks also differ from GitHub comments, which turn every newline into a break.

Why are my images broken in the VS Code Markdown preview?

Check three things. Relative paths like ./images/logo.png resolve from the Markdown file's folder, while a leading / starts at the workspace root. Images over plain http are blocked by the preview's default Strict security, so use https. And the file has to exist at that path in the workspace; markdown.validate.enabled will flag links that point nowhere.

Does VS Code support Mermaid diagrams?

Yes, built in since VS Code 1.121 (May 2026), when Matt Bierner's Markdown Preview Mermaid Support extension was merged into VS Code. Put the diagram in a fenced code block marked mermaid. Diagrams support pan and zoom with Alt (Option on macOS), and you can right-click to copy the source. Older versions need the extension.

Does the VS Code Markdown preview support math?

Yes. The built-in preview renders $...$ inline math and $$...$$ blocks with KaTeX, with no extension. Set markdown.math.enabled to false to turn it off, or use markdown.math.macros to define your own commands.

Why don't task list checkboxes show in the VS Code preview?

Task lists (- [ ] and - [x]) are a GitHub Flavored Markdown extension that VS Code's built-in renderer does not include, so they show as bullets with literal brackets. Install Markdown Checkboxes or Markdown All in One to render them as checkboxes.

How do I change the Markdown preview font or CSS?

For fonts, set markdown.preview.fontFamily, markdown.preview.fontSize, and markdown.preview.lineHeight. For anything else, list stylesheets in markdown.styles: https URLs, or paths relative to the folder open in the Explorer, for example ["styles/preview.css"]. The styles apply to the preview only.

Can VS Code export Markdown to PDF or HTML?

Not on its own. The Markdown PDF extension exports to PDF, HTML, PNG, or JPEG, and Markdown All in One has Print current document to HTML. Without installing anything, the browser-based Markdown to PDF tool on this site converts a .md file directly.

Why does Ctrl+Shift+V open a different preview than before?

An extension has taken over the shortcut. Markdown Preview Enhanced binds Ctrl+Shift+V and Ctrl+K V to its own preview window. Open Keyboard Shortcuts (Ctrl+K Ctrl+S), search for Ctrl+Shift+V, and remove the binding you do not want. In current VS Code the built-in shortcut toggles the same tab rather than opening a new one.

Why is my front matter showing as a table in the preview?

Since VS Code 1.121, the preview renders YAML front matter as a table instead of hiding it. Set markdown.preview.frontMatter to hide to get the old behavior, or codeBlock to show it as YAML.