Skip to content
All posts
7 min read
markdown
vscode
developers
guide
tools

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

ActionmacOSWindows / Linux
Preview to side⌘K VCtrl+K V
Preview in tab⌘Shift+VCtrl+Shift+V
Preview lockClick lock icon in preview toolbarsame

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:

![alt text](./assets/screenshot.png)

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 — ⌘B bold, ⌘I italic 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

TaskmacOSWindows / Linux
Bold selection⌘BCtrl+B
Italic selection⌘ICtrl+I
Preview side⌘K VCtrl+K V
Command palette⌘ShiftPCtrl+Shift+P
Go to symbol in file⌘ShiftOCtrl+Shift+O
Multi-cursor⌥ClickAlt+Click
Find in files⌘ShiftFCtrl+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

  1. Scaffold — copy template from GitHub README guide.
  2. Write in VS Code with Markdown All in One.
  3. Lint — markdownlint problems panel + heading audit.
  4. Preview — Ctrl+K V; check tables and Mermaid.
  5. Score — README health score or API audit.
  6. 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:

ScenarioTool
Quick paste-and-preview without opening a repoEditor
HTML ↔ Markdown conversionHTML to Markdown
Share preview link with a PMEditor share
Word count / reading time for a briefWord counter
Redact secrets before publishingRedact 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 *.mdx with Markdown or MDX language mode.
  • JSX components do not render in built-in preview — use npm run dev for 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

FeatureVS CodeObsidianBrowser editor
Lives next to code✅⚠️❌
Git integration✅via plugin❌
Wikilinks❌✅❌
Zero install sharing❌❌✅
Extension ecosystem✅✅limited
API automationvia CIvia plugins✅

Use VS Code for repo-bound docs; pair with Obsidian for personal notes and the browser editor for quick collaboration.

Quick reference

Shortcut / extensionAction
⌘K V / Ctrl+K VPreview to side
⌘Shift+V / Ctrl+Shift+VPreview tab
⌘B / Ctrl+BBold (with Markdown All in One)
Markdown All in OneTOC, lists, shortcuts
markdownlintStyle enforcement
PrettierFormat on save
Mermaid extensionDiagrams in preview
KaTeX extensionMath in preview
Ctrl+Shift+O / ⌘Shift+OJump 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.