VS Code Markdown Preview

How to preview Markdown in Visual Studio Code. Learn the built-in shortcut, split-editor workflow, path completions, and the settings that actually matter.

VS Code ships with a solid Markdown preview based on markdown-it. Everything CommonMark works out of the box; GitHub extras need extensions.

Start here

Two keyboard shortcuts cover 90% of the workflow

Open preview

Ctrl+Shift V / Cmd+Shift+V

Opens the current Markdown file in a preview tab, replacing the editor tab.

Open to the side

Ctrl+K V / Cmd+K V

Opens the preview in a split editor group so source and preview are visible together.

Jump to Section

Opening the Preview Preview Example Keyboard Shortcuts Path Completions Settings Common Mistakes Feature Support FAQ

Opening the Preview

VS Code recognizes files ending in .md, .markdown, or .mdx. Once a Markdown file is active, use one of the shortcuts below.

Open preview in current tab

# Open the Markdown preview

On Windows/Linux: Ctrl+Shift+V
On macOS: Cmd+Shift+V

Open preview to the side

# Open preview to the side

On Windows/Linux: Ctrl+K V
On macOS: Cmd+K V

If you prefer the mouse, click the icon that looks like a split editor with a magnifying glass in the top-right corner of the editor tab group, then select Open Preview or Open Preview to the Side.

What the Preview Looks Like

The left side is raw Markdown. The right side is what VS Code's built-in preview renders:

# Project README

## Features
- **Fast** builds with Turbopack
- Live Markdown preview
- Clean UI

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

| Task      | Command          |
|-----------|------------------|
| Dev       | `npm run dev`  |
| Build     | `npm run build`|
| Lint      | `npm run lint` |

VS Code preview

Project README

Features

Fast builds with Turbopack
Live Markdown preview
Clean UI

Usage

Run npm run dev and open http://localhost:3000.

Task	Command
Dev	`npm run dev`
Build	`npm run build`
Lint	`npm run lint`

Keyboard Shortcuts

The shortcuts you will use most often when writing Markdown in VS Code.

Action	Windows / Linux	macOS	What it does
Open preview	Ctrl+Shift+V	Cmd+Shift+V	Opens the current file in a Markdown preview tab
Open preview to the side	Ctrl+K V	Cmd+K V	Opens the preview next to the editor
Toggle source/preview	Ctrl+Shift+V	Cmd+Shift+V	While preview is focused, switches back to source view
Command Palette	Ctrl+Shift+P	Cmd+Shift+P	Type Markdown to filter Markdown-related commands
Zen mode	Ctrl+K Z	Cmd+K Z	Distraction-free writing, useful with split preview

Path Completions

VS Code completes file paths inside image and link syntax. Type ./ or ../ and an IntelliSense menu appears with files and folders. This prevents the most common cause of broken local links and images.

Path completion in Markdown

![Diagram](./assets/diagram.png)

[Sibling doc](../notes/setup.md)

Settings That Matter

Search for these settings by name in VS Code Settings (Ctrl+, or Cmd+,). All start with markdown..

Setting	Why it matters
markdown.preview.doubleClickToSwitchToEditor	Double-clicking the preview switches back to the source editor.
markdown.preview.scrollEditorWithPreview	Scrolls the editor when you scroll the preview.
markdown.preview.scrollPreviewWithEditor	Scrolls the preview when you scroll the editor.
markdown.styles	Array of CSS file URIs to apply to the preview (use absolute workspace paths).
markdown.trace	Log level for debugging extension-provided Markdown rendering.

Common Mistakes

The errors that cause the most confusion when previewing Markdown in VS Code.

Does not work

![Logo](/images/logo.png)

Use instead

![Logo](./images/logo.png)

VS Code's preview resolves image paths relative to the Markdown file. A leading slash points to the workspace root, which only works when the file is at the root.

Does not work

| Name | Role |
| Alice | Developer |
| Bob | Designer |

Use instead

| Name  | Role      |
|-------|-----------|
| Alice | Developer |
| Bob   | Designer  |

Tables need a separator row (|---|---|) between the header and data. Without it, the preview renders plain text.

Does not work

[[Related Note]]

Use instead

[Related Note](../notes/related.md)

Wikilinks are Obsidian-only. VS Code's built-in preview does not recognize [[...]] syntax unless you install an extension.

Does not work

> [!warning]
> Watch out

Use instead

> **Warning**
> Watch out

GitHub callout syntax (> [!warning]) is not rendered in VS Code's built-in preview. Use bold text or plain callout phrasing, or install a GitHub Alerts extension.

Feature Support

What works in VS Code's built-in preview and what needs an extension.

Feature	Status	Notes
Bold / italic	Yes	Standard Markdown emphasis.
Headings	Yes	Six levels plus automatic TOC via extensions.
Links	Yes	Relative and absolute URLs. Paths resolve relative to the file.
Images	Yes	Relative paths work best. Data URLs are also supported.
Lists	Yes	Ordered, unordered, and nested lists.
Task lists	Yes	- [x] renders as a disabled checkbox.
Code blocks	Yes	Syntax highlighting for fenced code with language identifiers.
Tables	Yes	GFM-style pipe tables with alignment.
Blockquotes	Yes	Single-line and nested.
Strikethrough	Yes	~~text~~ renders with a line-through.
Footnotes	No	Not part of the built-in renderer. Use an extension or export via Pandoc.
Math (KaTeX)	Extension	Install an extension such as Markdown+Math to render $...$ and $$...$$.
Mermaid	Extension	Use the Markdown Preview Mermaid extension.
Diagrams-as-code	Extension	PlantUML, Structurizr, and others require extensions.
Wikilinks [[...]]	Extension	Install an Obsidian-style or wikilink extension.
GitHub alerts (> [!note])	Extension	Use a GitHub Alerts or callout extension for styled boxes.

Frequently Asked Questions

How do I preview Markdown in VS Code?

Open any .md or .markdown file and press Ctrl+Shift+V on Windows/Linux, or Cmd+Shift+V on macOS. The preview opens in a new tab. To see the preview next to the editor instead of replacing it, use Ctrl+K V (Cmd+K V).

Can I keep the Markdown preview open next to my editor?

Yes. Use Ctrl+K V (Windows/Linux) or Cmd+K V (macOS) to open the preview in a split group. Any change you save updates the preview automatically; live updates while typing are controlled by Auto Save and extension behavior.

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

VS Code's built-in preview uses markdown-it, the same engine as GitHub, but GitHub adds its own extensions: task list interactivity, autolinks, heading anchors, math, Mermaid, and alerts (> [!note]). VS Code supports some of these only through extensions or when publishing with a static-site generator.

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

The preview resolves image paths relative to the Markdown file, not the workspace root. Use relative paths like ./images/logo.png. Avoid leading slashes unless the file is at the workspace root. Network URLs must be reachable from your machine.

Does VS Code support Mermaid diagrams?

Not by default. Install the 'Markdown Preview Mermaid Support' extension by Matt Bierner. After installing, fenced code blocks marked ```mermaid render as diagrams in the preview.

How do I autocomplete image and link paths in Markdown?

VS Code provides path completions out of the box. Type ./ or ../ inside image or link syntax and an IntelliSense menu shows files and folders. This works for both ![alt](./) and [label](./).

How do I change the Markdown preview font or CSS?

Open Settings and search for 'markdown.styles'. Add an array of absolute file paths to custom CSS files in your workspace, for example ['/workspace/styles/preview.css']. The styles apply only to the preview, not the editor.

Related Markdown Guides

VS Code is a Markdown editor, not a flavor. Compare it to other tools and reference the core syntax when you need it.

Full Markdown Cheat Sheet GitHub Markdown (GFM)Markdown Table Syntax Obsidian Markdown Notion Markdown Markdown Link Syntax