How to Preview Markdown Files in VS Code
Preview Markdown in VS Code with shortcuts, side-by-side editing, Mermaid, math, security settings, troubleshooting, and automation options.
VS Code includes a Markdown preview, so you do not need a separate preview application. Open a .md file, then use Ctrl+Shift+V on Windows/Linux or Shift+Command+V on macOS to toggle the preview. To keep the source and rendered document beside each other, use Ctrl+K V on Windows/Linux or Command+K V on macOS. Microsoft documents this built-in workflow in Markdown and Visual Studio Code.
Open a Markdown preview
- Open or create a file whose name ends in
.md. - Press Ctrl+Shift+V on Windows/Linux, or Shift+Command+V on macOS.
- VS Code opens the rendered Markdown preview for the active file.
You can also right-click the editor tab and choose Open Preview. From the Command Palette (Ctrl+Shift+P on Windows/Linux or Command+Shift+P on macOS), run Markdown: Open Preview or Markdown: Open Preview to the Side.
Open the editor and preview side by side
Use Ctrl+K, then V on Windows/Linux, or Command+K, then V on macOS. VS Code opens the preview beside the Markdown editor. Edit the source on one side and watch the rendered document update on the other.
Scrolling either pane normally moves the other pane to the matching location. The line selected in the editor is marked in the preview, which makes long documents easier to navigate.
Keep a preview attached to one file
By default, the preview follows the active Markdown file. If you switch files and want the existing preview to stay attached to its original document, open the Command Palette and run Markdown: Toggle Preview Locking. This is useful when comparing several files or keeping documentation visible while editing code.
Write Markdown that the preview can render
# Project notes
A paragraph with **bold** and *italic* text.
- First item
- Second item
[Project documentation](https://example.com)
```js
console.log("Code fences keep source formatting");
```Save the file, then look at the preview. Relative links and image paths are resolved from the Markdown file’s location, so check the path and capitalization when an asset is missing.
Render Mermaid diagrams and KaTeX math
The built-in preview supports Mermaid diagrams and KaTeX mathematics. Put Mermaid in a fenced block labeled mermaid:
```mermaid
flowchart LR
edit[Edit .md] --> preview[VS Code preview]
preview --> share[Share documentation]
```Larger Mermaid diagrams support panning and zooming. For math, use single dollar signs for inline expressions and double dollar signs for display equations:
Inline: $E = mc^2$
$$
\int_0^1 x^2\,dx = \frac{1}{3}
$$Recent VS Code releases include Mermaid support through the built-in Mermaid Markdown Features extension, which also covers Markdown previews, notebook cells, and chats.
Preview Markdown diffs and choose default associations
Markdown diffs can be reopened in the Markdown Preview editor. If you prefer the preview editor to be the default for .md files, configure workbench.editorAssociations. To target only diffs, use workbench.diffEditorAssociations.
{
"workbench.editorAssociations": {
"*.md": "vscode.markdown.preview.editor"
}
}Use these settings when a team consistently reviews rendered documentation. Keep the normal text editor available when you need to edit source directly.
Customize preview styling
A workspace can load additional CSS through the markdown.styles setting. Extensions can contribute preview styles and scripts through markdown.previewStyles and markdown.previewScripts.
{
"markdown.styles": [
"./docs/markdown.css"
]
}Use workspace-relative paths so collaborators receive the same appearance. Preview styles affect presentation; they do not change the Markdown source or the generated content.
Security: blocked scripts, images, and untrusted workspaces
Strict preview security is the recommended default. It disables script execution, loads only trusted content, and blocks images served over plain http. If a document references an HTTP image, use HTTPS or change the preview’s security setting only when you understand the source.
Allow insecure content permits HTTP resources while scripts remain disabled. Disable removes additional preview protections and allows scripts; use it only for Markdown files and workspaces you trust.
Workspace Trust adds another boundary for unfamiliar repositories. Restricted Mode helps prevent automatic code execution by VS Code and extensions until you trust the folder. Do not trust a repository merely to make a preview render; inspect its files and dependencies first.
Install extensions safely
Most Markdown preview work needs no extension. Add one only for a capability you actually need, such as specialized syntax or a publishing workflow. Open Extensions from the Activity Bar or press Ctrl+Shift+X.
- Check the publisher and repository.
- Read the license, permissions, ratings, and Q&A.
- Prefer maintained projects with clear support information.
- Review automatic updates and workspace settings after installation.
An extension host can read and write files, make network requests, run processes, and modify workspace settings. Treat extensions as code running in your development environment.
Common problems and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The shortcut does nothing | The Markdown editor is not active, or another keybinding overrides it. | Click inside the .md editor, then use the Command Palette and run Markdown: Open Preview. Check Keyboard Shortcuts for conflicts. |
| The preview opens in the wrong location | The side-by-side command was not used. | Run Markdown: Open Preview to the Side or press Ctrl+K, V / Command+K, V. |
| Changes are not reflected | The preview is locked to another file, or the file has unsaved changes. | Check Markdown: Toggle Preview Locking, then save and reopen the preview. |
| Images show as broken | The relative path, filename case, or URL is wrong; an HTTP URL may also be blocked. | Verify the path from the Markdown file, use matching capitalization, prefer HTTPS, and review preview security. |
| Mermaid appears as code | The fence is not labeled mermaid, or Mermaid support is unavailable. |
Use a fenced block beginning with ```mermaid and ensure the built-in Mermaid Markdown Features extension is enabled. |
| Math appears as plain text | The delimiters are incorrect. | Use $...$ for inline math or $$...$$ for a display equation. |
| Scripts or embedded content do not run | Strict security blocks scripts by design. | Keep scripts disabled for untrusted content. If the workspace is yours and the content is safe, review the security setting before changing it. |
| An extension changes the preview unexpectedly | Preview CSS or scripts supplied by an extension override defaults. | Inspect extension contributions, disable the extension temporarily, and compare the result in a trusted workspace. |
Performance and reliability checklist
- Keep very large diagrams and image assets outside the main document when possible.
- Use local, compressed images and stable HTTPS URLs.
- Split long documentation into linked pages when navigation becomes slow.
- Lock a preview when editing multiple files so it does not follow every tab change.
- Use Restricted Mode for repositories you have not reviewed.
- Keep preview extensions to the minimum required set.
VS Code renders the preview locally. Network images and extension-provided content can still introduce latency or availability problems, so a self-contained document with local assets is the most predictable for offline review.
Or skip the browser setup
If your goal is to capture a rendered page or documentation URL rather than inspect Markdown source, ScreenshotNeo provides a website screenshot API. Its consent step accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI clients such as Claude and Cursor.
See the ScreenshotNeo API documentation for all options.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes full-page capture with lazy images loaded, element selectors, dark mode, device presets, custom viewports, retina scale, PDF output, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Its parameter names also match those used by other screenshot APIs, which helps when switching.
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Do I need a Markdown extension?
No. VS Code supports Markdown files and preview out of the box. Extensions are optional for extra syntax, styling, or publishing workflows.
Can I keep the preview open while editing another file?
Yes. Toggle preview locking to keep it attached to one document while you work elsewhere.
Why are HTTP images blocked?
Strict preview security blocks insecure HTTP content. Prefer HTTPS; changing the setting reduces protection.
Can the preview execute JavaScript?
Scripts are disabled by default. Only consider enabling them for Markdown and workspaces you fully trust.
