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"
}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` |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 |
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.
| Action | Windows / Linux | macOS |
|---|---|---|
| Toggle preview in the same tab | Ctrl+Shift+V | Cmd+Shift+V |
| Open preview to the side | Ctrl+K V | Cmd+K V |
| Command Palette | Ctrl+Shift+P or F1 | Cmd+Shift+P or F1 |
| Go to a heading in this file | Ctrl+Shift+O | Cmd+Shift+O |
| Go to a heading in any file | Ctrl+T | Cmd+T |
| Suggest paths, headings, snippets | Ctrl+Space | Ctrl+Space |
| Rename a heading and update links | F2 | F2 |
| Find all links to a heading or file | Shift+Alt+F12 | Shift+Option+F12 |
| Expand / shrink selection | Shift+Alt+Right / Left | Ctrl+Shift+Cmd+Right / Left |
| Open Settings | Ctrl+, | Cmd+, |
| Zen mode | Ctrl+K Z | Cmd+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:
| Type this | VS Code suggests |
|---|---|
| . - Moving files: set
markdown.updateLinksOnFileMove.enabledtopromptoralwaysand 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).
| Setting | Default | What it does |
|---|---|---|
| markdown.preview.breaks | false | true turns every newline into a line break, like a GitHub comment |
| markdown.preview.fontFamily / fontSize / lineHeight | system font / 14 / 1.6 | Preview typography |
| markdown.styles | [] | Extra CSS for the preview: https URLs or paths relative to the workspace folder |
| markdown.preview.frontMatter | table | Show YAML front matter as a table, a codeBlock, or hide it |
| markdown.math.enabled | true | KaTeX math rendering in the preview |
| markdown.preview.linkify | true | Turn bare URLs into links |
| markdown.preview.scrollPreviewWithEditor | true | Scroll sync from editor to preview (scrollEditorWithPreview is the reverse) |
| markdown.preview.doubleClickToSwitchToEditor | false | Double-click the preview to jump to the source (off since 1.120) |
| markdown.validate.enabled | false | Flag links to missing files, headings, and reference definitions |
| markdown.updateLinksOnFileMove.enabled | never | prompt or always rewrites links when a file is moved or renamed |
| markdown.suggest.paths.enabled | true | Path and heading completions inside links |
| markdown.editor.pasteUrlAsFormattedLink.enabled | smartWithSelection | Paste a URL over selected text to make a link |
| markdown.editor.filePaste.enabled / drop.enabled | smart | Paste 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.
| Feature | Built in? | Notes |
|---|---|---|
| Headings, bold, italic, links, lists, quotes | Yes | Standard CommonMark |
| Tables | Yes | GFM pipe tables with alignment |
| Strikethrough | Yes | ~~text~~ |
| Fenced code with highlighting | Yes | highlight.js, by language identifier |
| Math ($...$ and $$...$$) | Yes | Built in with KaTeX; turn off with markdown.math.enabled |
| Mermaid diagrams | Yes | Built in since 1.121 (May 2026); before that, an extension |
| YAML front matter | Yes | Shown as a table by default since 1.121 |
| Raw HTML | Yes | Passed through; scripts are blocked by the preview's security level |
| Bare URL autolinks | Yes | markdown.preview.linkify |
| Single newline as a line break | No | Off by default; set markdown.preview.breaks |
| Task lists - [ ] | Extension | Markdown Checkboxes, or Markdown All in One |
| GitHub alerts > [!NOTE] | Extension | Markdown All in One |
| Footnotes [^1] | Extension | Markdown Footnotes |
| Emoji :shortcodes: | Extension | Markdown Emoji |
| Wikilinks [[...]] | Extension | Foam or another notes extension |
| PlantUML, Graphviz, code chunks | Extension | Markdown Preview Enhanced |
| Export to PDF or HTML | Extension | Markdown 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-oneEditing 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-markdownlintUnderlines 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-enhancedA 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-previewMatt 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-pdfExports 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 twoUse instead
Line one\
Line twoDoes not work
Line one··
Line twoUse instead
"[markdown]": {
"files.trimTrailingWhitespace": false
}Does not work
Use instead
Does not work
- [ ] Write docs
- [x] Ship itUse instead
Install Markdown Checkboxes
or Markdown All in OneDoes not work
> [!WARNING]
> Watch outUse instead
> **Warning**
> Watch outDoes not work
| Name | Role |
| Alice | Developer |Use instead
| Name | Role |
|-------|-----------|
| Alice | Developer |Does not work
[[Related Note]]Use instead
[Related Note](../notes/related.md)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.