VS Code Markdown: Complete Guide to Extensions, Preview & Shortcuts (2026)
Master Markdown in Visual Studio Code — built-in preview, essential extensions, keyboard shortcuts, markdownlint, Mermaid, math, and README workflows that ship faster.
Visual Studio Code is the default Markdown environment for millions of developers. READMEs, API docs, RFCs, and changelog entries all live as .md files next to source code — and VS Code meets you there with zero context switching.
But the built-in experience only gets you halfway. The right extensions, shortcuts, and workspace settings turn VS Code from a plain text editor into a documentation workstation that rivals dedicated Markdown apps.
This guide covers everything: preview, extensions, linting, snippets, multi-root workspaces, and how to pair VS Code with browser tools and the Markdown API when you need more.
Built-in Markdown features
VS Code ships with Markdown support out of the box — no extensions required.
Open preview
| Action | macOS | Windows / Linux |
|---|---|---|
| Preview to side | ⌘K V | Ctrl+K V |
| Preview in tab | ⌘Shift+V | Ctrl+Shift+V |
| Preview lock | Click lock icon in preview toolbar | same |
The preview renders GitHub Flavored Markdown — tables, task lists, strikethrough, fenced code, autolinks.
Sync scroll
Enable Markdown › Preview: Scroll Preview With Editor in Settings. Editing line 240 highlights the matching section in preview — essential for long READMEs.
Drag and drop images
Drag an image into a .md file. VS Code inserts:

Configure Markdown › Copy Files: Destination to control where dropped images land — ./assets keeps repos tidy.
Essential extensions
Markdown All in One
The must-have extension. Adds:
- Table of contents —
⌘ShiftP→ "Create Table of Contents" - Keyboard shortcuts —
⌘Bbold,⌘Iitalic on selected text - List editing — Enter continues lists; Tab indents
- Auto preview — optional sync on save
// settings.json
"markdown.extension.toc.levels": "2..4",
"markdown.extension.print.absoluteImgPath": false
Generate TOCs in browser with the TOC generator when sharing docs outside VS Code.
markdownlint
Enforces style consistency — heading increments, line length, trailing spaces.
"markdownlint.config": {
"MD013": false,
"MD033": false,
"MD041": false
}
MD013 (line length) is often disabled for tables and URLs. MD033 (inline HTML) if you use <details> in READMEs. MD041 (first line H1) if frontmatter precedes the title.
Run the GFM checklist for a second opinion before opening a PR.
Prettier (with Markdown support)
"[markdown]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true
}
Prettier wraps prose, aligns tables imperfectly but consistently, and normalizes list markers. For stricter GFM table alignment, use the table generator.
Markdown Preview Mermaid Support
Renders ```mermaid blocks in the built-in preview — flowcharts, sequence diagrams, Gantt charts.
```mermaid
sequenceDiagram
Client->>API: POST /render
API-->>Client: HTML
```
Prototype diagrams in the diagram tools hub.
Markdown Math (KaTeX)
For `$inline$` and $$block$$ math in preview:
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$
Match editor behavior with the site's math inventory to catch unclosed delimiters.
Workspace settings for doc repos
Drop in .vscode/settings.json:
{
"files.associations": {
"*.mdx": "markdown"
},
"markdown.preview.breaks": true,
"markdown.preview.linkify": true,
"editor.wordWrap": "on",
"editor.quickSuggestions": {
"comments": "off",
"strings": "off",
"other": "off"
},
"[markdown]": {
"editor.wordWrap": "on",
"editor.lineNumbers": "off"
}
}
editor.quickSuggestions off stops autocomplete mid-word while writing prose — a small quality-of-life win technical writers swear by.
Keyboard shortcuts cheat sheet
| Task | macOS | Windows / Linux |
|---|---|---|
| Bold selection | ⌘B | Ctrl+B |
| Italic selection | ⌘I | Ctrl+I |
| Preview side | ⌘K V | Ctrl+K V |
| Command palette | ⌘ShiftP | Ctrl+Shift+P |
| Go to symbol in file | ⌘ShiftO | Ctrl+Shift+O |
| Multi-cursor | ⌥Click | Alt+Click |
| Find in files | ⌘ShiftF | Ctrl+Shift+F |
Go to symbol (Ctrl+Shift+O) jumps between # headings in the current file — a built-in outline navigator.
Snippets for faster README writing
User snippets in markdown.json:
{
"GFM Table": {
"prefix": "table",
"body": [
"| ${1:Column} | ${2:Column} |",
"| --- | --- |",
"| ${3:cell} | ${4:cell} |",
"$0"
]
},
"GFM Alert": {
"prefix": "alert",
"body": [
"> [!${1|NOTE,TIP,IMPORTANT,WARNING,CAUTION|}]",
"> ${2:Content}",
"$0"
]
},
"Code fence": {
"prefix": "fence",
"body": ["```${1:typescript}", "${2}", "```", "$0"]
}
}
Type table + Tab for a pipe table scaffold. See the GitHub README guide for full README structure.
Multi-root workspaces
Document monorepos with a .code-workspace file:
{
"folders": [
{ "path": "packages/core", "name": "Core" },
{ "path": "packages/cli", "name": "CLI" },
{ "path": "docs", "name": "Documentation" }
],
"settings": {
"markdownlint.config": { "MD041": false }
}
}
Search across all packages (Ctrl+Shift+F) when renaming an API endpoint — find every doc reference in one pass.
Linting in CI with the Markdown API
VS Code linting is local. For team enforcement, add CI:
# .github/workflows/docs.yml
name: Docs
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate Markdown
run: |
for f in $(find docs -name '*.md'); do
curl -sf -X POST https://trymarkdownviewer.com/api/v1/validate \
-H "Authorization: Bearer ${{ secrets.MDV_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{\"markdown\": $(jq -Rs . < "$f")}" || exit 1
done
Also available: audit GFM, audit headings, README score.
README workflow end-to-end
- Scaffold — copy template from GitHub README guide.
- Write in VS Code with Markdown All in One.
- Lint — markdownlint problems panel + heading audit.
- Preview —
Ctrl+K V; check tables and Mermaid. - Score — README health score or API audit.
- PR — CI validate step blocks merge on errors.
When to leave VS Code for browser tools
VS Code excels at files in repos. Reach for browser tools when:
| Scenario | Tool |
|---|---|
| Quick paste-and-preview without opening a repo | Editor |
| HTML ↔ Markdown conversion | HTML to Markdown |
| Share preview link with a PM | Editor share |
| Word count / reading time for a brief | Word counter |
| Redact secrets before publishing | Redact tool |
Many developers draft in the browser, commit from VS Code — both use GFM, so output matches.
MDX in VS Code
MDX (Markdown + JSX) powers Next.js and Docusaurus docs. VS Code tips:
- Install MDX extension for syntax highlighting.
- Associate
*.mdxwith Markdown or MDX language mode. - JSX components do not render in built-in preview — use
npm run devfor real preview.
Edit frontmatter visually with the frontmatter editor when YAML errors confuse the build.
Common VS Code Markdown mistakes
1. Trusting preview for math/Mermaid without extensions. Install KaTeX and Mermaid plugins or preview in the browser editor.
2. Broken relative image paths. ./assets/img.png must exist relative to the .md file — CI won't catch missing files without a link checker.
3. Mixing tab and space indentation in lists. markdownlint flags MD005/MD007; use format-on-save.
4. Giant single README files. Split into docs/ and link — GitHub renders multi-file docs fine.
5. No settings.json in doc repos. New contributors get inconsistent wrap and lint behavior.
6. Committing .vscode/ selectively. Commit shared settings; gitignore personal overrides.
VS Code vs. dedicated Markdown apps
| Feature | VS Code | Obsidian | Browser editor |
|---|---|---|---|
| Lives next to code | ✅ | ⚠️ | ❌ |
| Git integration | ✅ | via plugin | ❌ |
| Wikilinks | ❌ | ✅ | ❌ |
| Zero install sharing | ❌ | ❌ | ✅ |
| Extension ecosystem | ✅ | ✅ | limited |
| API automation | via CI | via plugins | ✅ |
Use VS Code for repo-bound docs; pair with Obsidian for personal notes and the browser editor for quick collaboration.
Related articles
- GitHub README guide — structure, badges, templates
- Docs-as-code guide — CI pipelines and SSG
- Markdown to HTML guide — render for CMS embeds
- Best Markdown editors — how VS Code compares
- Markdown cheat sheet — syntax reference
Quick reference
| Shortcut / extension | Action |
|---|---|
| ⌘K V / Ctrl+K V | Preview to side |
| ⌘Shift+V / Ctrl+Shift+V | Preview tab |
| ⌘B / Ctrl+B | Bold (with Markdown All in One) |
| Markdown All in One | TOC, lists, shortcuts |
| markdownlint | Style enforcement |
| Prettier | Format on save |
| Mermaid extension | Diagrams in preview |
| KaTeX extension | Math in preview |
| Ctrl+Shift+O / ⌘Shift+O | Jump to heading |
VS Code is already on your machine. Install two extensions, tune three settings, and your Markdown workflow matches a dedicated writing app — without leaving the repository.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
An honest, feature-by-feature comparison of the most popular Markdown editors — browser vs desktop, free vs paid, collaboration, export, diagrams, and which one fits your workflow.
A power-user tutorial for advanced Markdown tasks — diffing revisions, validating Mermaid, redacting secrets, normalizing structure, merging and splitting docs, and managing footnotes.
Ship documentation from Git with Markdown — repo structure, Hugo, Docusaurus, MDX, review workflows, CI linting, API automation, and patterns documentation teams use at scale.