MD Preview

Enhanced Markdown experience for VS Code: a custom React webview preview with an embedded outline, a rich set of markdown-it plugins, syntax highlighting, KaTeX math, Mermaid diagrams, and theme-aware styling that follows every VS Code color theme automatically.

Built for VS Code ^1.106.0.

Features

• Real-time preview in a custom React webview — no page reload, no theme flicker.
• Embedded outline with scroll-spy: the active heading is highlighted as you scroll; clicking a heading scrolls the preview (you stay in the preview, never dumped back into the editor).
• Markdown Files explorer view listing every .md file in the workspace (ignores node_modules, .git, out, dist, build, .vscode, coverage and dot-folders).
• Clickable file links — clicking a relative link ([other doc](https://github.com/tvhoanganh/md-preview/blob/HEAD/notes.md)) in the preview opens Markdown targets as a rendered preview (same tab group) and other file types in the editor; external (http(s)://) links open in a browser tab; in-page #anchors scroll the preview.
• Markdown-it plugins — see Supported Markdown.
• Theme-aware UI — colors adapt to any VS Code color theme (dark/light/high-contrast) using VS Code's own CSS variables; no theme-specific code in the host.

Getting started

From a workspace with Markdown files:

1. Open the Explorer → the Markdown Files view lists all .md files. Click a file to open its preview.
2. Or use the commands below from a Markdown editor.

Commands & keybindings

From inside the preview:

• ⌘+Alt+O / Ctrl+Alt+O — toggle the outline pane.
• ⌘+Alt+V / Ctrl+Alt+V — jump to the editor.
• The toolbar button switches back to the editor for the previewed document.
• Opening a preview again with the same command toggles it closed.
• External (http(s)://) links open in a new browser tab.

Supported Markdown

Everything markdown-it provides (GFM-flavored: tables, strikethrough, task lists, autolinks, typographer…), plus:

| Feature | Syntax | Notes | |---|---|---| | Admonition "callout" boxes | ::: note Title … ::: | Also warning, tip, info, success, danger | | Footnotes | Here[^1] + [^1]: text | | | Definition lists | Term/: definition | | | Abbreviations | *[HTML]: Hyper Text Markup Language | | | Emoji (full set) | :rocket: | | | Sub / Superscript | H~2~O, x^2^ | | | Highlight / Insert | ==mark==, ++ins++ | | | Custom attributes | # Title {#my-id .custom} | Add id/class to any element | | Task lists (GitHub) | - [ ] todo, - [x] done | Rendered as clickable checkboxes | | GFM tables | \| a \| b \| with :---: alignment | Alignment, multiline cells, rowspan | | KaTeX math | Inline $a^2$, display $$\frac{1}{2}$$ | Rendered server-side; works offline | | Mermaid diagrams | ```mermaid … ```` | Bundled into the preview; works offline | | Syntax highlighting | ````javascript ```` etc. | highlight.js in the host process | | Include files | !!!include (path/to/file.md) !!! | Path resolved relative to the current file |

Math notes

• Both $...$ (inline) and $$...$$ (block) are enabled. Math rendering is worth it, but it means a lone $ in prose is treated as math delimiters — escape it with \$ if you need a literal dollar sign.

Mermaid notes

• Mermaid is bundled into the webview (import mermaid compiled by esbuild) — no CDN, works offline.
• Diagrams use a fixed, curated palette (vivid pastels: tinted nodes, saturated borders, colored edges) so they look the same on every VS Code color theme, dark or light.

Theming

• All colors come from VS Code's own --vscode-* CSS variables, so any installed color theme (One Dark Pro, GitHub, Dracula, Solarized, high-contrast…) styles the preview correctly — including user workbench.colorCustomizations.

• Syntax-token colors use a light/dark palette selected by the editor's theme mode, with optional per-theme overrides (One Dark Pro, GitHub Dark, Monokai out of the box). To add your own, add a block like this to src/webview/styles.css:

  body[data-vscode-theme-id="Your Theme"] {
      --md-token-comment: #5c6370;
  }
  

Development

npm install       # install dependencies
npm run compile   # tsc + bundle the webview (out/)
npm run watch     # incremental rebuild on save

• Press F5 in VS Code to launch an Extension Development Host and try the preview on a sample .md.
• Tip: run npm run watch while iterating, then reload the dev host to pick up new bundles.
• Lint: the repo ships a lint script but eslint is not (yet) a dependency; run your own eslint if you want it.

Project layout

src/
  extension.ts              # activation, commands, Markdown Files tree view
  markdownConfig.ts         # markdown-it setup + plugin wiring
  outline/headings.ts       # heading parsing + outline tree
  preview/MarkdownPreviewManager.ts  # preview panel lifecycle + state
  webview/                  # React app: PreviewPanel, OutlinePanel, mermaid, styles
  types/                    # ambient types for plugins without declarations

Changelog

0.0.13

• Colorful diagram palette: vivid pastel nodes, saturated colored borders and colored edges — applied consistently across every chart type (flow, sequence, class, state, ER, gantt, pie, journey, git, quadrant, timeline, xy, requirement, mindmap, block).

0.0.12

• Default diagram palette switched to Catppuccin Latte.

0.0.11

• Diagrams use a fixed (theme-independent) color palette; styling polish for rendered diagrams.

0.0.10

• Mermaid now actually renders — fixed two root causes: raw [r,g,b] color arrays passed to themeVariables (crashed initialize), and a second acquireVsCodeApi() call throwing (swallowed all diagnostics). Emits <pre class="mermaid"> and renders with mermaid.run() through an imperative watcher (no reliance on React effects).

0.0.9

• Bundle mermaid into the webview via import mermaid (esbuild) — removed the CDN dependency.

0.0.8

• Ship a local copy of mermaid instead of loading from a CDN.

0.0.7

• Render relative images (![alt](https://github.com/tvhoanganh/md-preview/raw/HEAD/img.png)) inside the preview via webview.asWebviewUri.

0.0.6

• Clicking a Markdown link opens the target as a rendered preview in the same tab group; other file types open in the editor.

0.0.5

• Markdown links open as a rendered preview (to the side).

0.0.4

• Robust link resolution (document folder, then workspace roots) + capture-phase click handling in the webview.

0.0.3

• Fix clicking of links inside the webview (host-side handler).

0.0.2

• Extension icon.

0.0.1

• Initial release: React webview preview, embedded outline with scroll-spy, Markdown Files explorer view, markdown-it plugins, KaTeX math, syntax highlighting, theme-aware UI.

License

MIT