MDX Preview for Visual Studio Code

A modern, actively maintained successor to the original MDX Preview by Xiaoyi Chen. Built on MDX 3 with React 19, framework support, Tailwind CSS, and a two-mode security model.

Features

• Live Preview - Instant preview as you type without a dev server
• React Components - Full import and rendering support in Trusted Mode
• Framework Shims - Auto-detection and built-in shims for Docusaurus, Starlight, Nextra, and Next.js
• Tailwind CSS - Built-in Tailwind v4 compilation with auto-detection
• Syntax Highlighting - Shiki-powered code blocks with 100+ languages and 24 themes
• Preview Themes - 16 themes (GitHub, Atom, Solarized, etc.) with auto light/dark switching
• Mermaid Diagrams - Flowcharts, sequence diagrams, state diagrams, and more
• PlantUML Diagrams - Server-side rendering via configurable PlantUML server
• Graphviz Diagrams - Client-side DOT graph rendering via WASM engine
• Math Expressions - KaTeX for inline ($...$) and block ($$...$$) math
• GitHub Alerts - NOTE, TIP, WARNING, CAUTION, IMPORTANT callouts
• Image Lightbox - Fullscreen image viewer with gallery navigation, zoom, and pan
• Preview Zoom - Preview-scoped zoom commands without changing VS Code's global zoom
• Export to HTML - Save the rendered preview as a standalone .html file from the toolbar or command palette
• Authoring Feedback - Source-line highlighting, MDX outline, symbols, and frontmatter-aware completions
• Editor ↔ Preview Sync - Opt-in scroll sync between editor and preview, plus Cmd/Ctrl+Click jump from preview to source
• Custom Plugins - Load remark/rehype plugins from your project
• TypeScript Preview - Preview .tsx/.ts files that render to #root
• Safe/Trusted Modes - Safe Mode for untrusted content, Trusted Mode for full rendering

Quick Start

1. Install npm dependencies in your workspace (npm install)
2. Open an .mdx or .md file
3. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run "MDX: Open MDX Preview", or press Cmd+K X / Ctrl+K X

Preview automatically updates as you type. The MDX extension is installed automatically for syntax highlighting.

Framework Support

MDX Preview detects your framework from package.json and provides compatible component shims:

See Frameworks for details and examples.

Custom Layout

Apply a custom layout by exporting a default value:

import Layout from './components/Layout';

export default Layout;

## Hello

Content wrapped in Layout.

Or set a global layout path via mdx-preview.preview.mdx.customLayoutFilePath. When nothing is specified, VS Code Markdown styles are applied by default (toggle with mdx-preview.preview.useVscodeMarkdownStyles).

MDX Transclusion

Import other .mdx or .md files as components:

import Introduction from './Introduction.mdx';

<Introduction />

Editor ↔ Preview Sync

Two opt-in features keep the editor and preview aligned while you author:

Scroll sync — set mdx-preview.preview.scrollSync to one of:

Sync is anchored around the top-third reading band (~35% from the top) so the line you're focused on stays in roughly the same vertical position on both sides instead of snapping to center.

Cmd/Ctrl+Click to source — hold Cmd (macOS) or Ctrl (Windows/Linux) and click any rendered block in the preview to open the editor at that source line. Clicks on interactive elements (links, buttons, form fields, <details>) still behave normally.

Both features work in Safe Mode and Trusted Mode. They rely on MDX's data-source-line annotations, so they're available for any block the compiler can map (paragraphs, headings, lists, tables, code blocks, callouts, etc.).

JavaScript/TypeScript Preview

Preview React apps that render to #root:

import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);

Configuration

Per-project customization via .mdx-previewrc.json (Trusted Mode only):

{
  "remarkPlugins": ["remark-toc", ["remark-emoji", { "emoticon": true }]],
  "rehypePlugins": ["rehype-external-links"],
  "components": {
    "Button": "./src/components/Button.tsx"
  }
}

Plugins must be installed in your project's node_modules. See Configuration for the full reference.

Security

Safe Mode (default) - Renders MDX as static HTML. No JavaScript execution, no imports, strict CSP. Used automatically in untrusted workspaces.

Trusted Mode - Full MDX rendering with React components and imports. Requires a trusted workspace and mdx-preview.preview.enableScripts enabled. Only available for local workspaces.

Code is only evaluated inside VS Code's isolated webview iframe. MDX files can only require dependencies within your active workspace. By default, only HTTPS content is allowed. You can change security settings through mdx-preview.preview.security or "MDX: Change Security Settings".

See Security for the full security model.

Extension Settings

This table covers the most common settings. See Configuration for the full reference, including Tailwind tuning (mdx-preview.tailwind.*) and advanced options (mdx-preview.advanced.*).

Webview Limitations

VS Code webviews have some inherent limitations:

• No Service Workers or Local Storage
• Use MemoryRouter instead of BrowserRouter for React Router
• Some third-party components may not work

Troubleshooting

Component doesn't render? Open "Developer: Open Webview Developer Tools" from the Command Palette and check the console. Make sure you're in Trusted Mode. Try toggling mdx-preview.build.useSucraseTranspiler.

Preview shows "Safe Mode"? Trust the workspace via "Workspaces: Manage Workspace Trust", then set mdx-preview.preview.enableScripts to true.

Framework not detected? Verify the framework package is in your package.json, or manually set mdx-preview.framework.

See Troubleshooting for more.

Documentation

• Configuration - Full configuration reference
• Frameworks - Framework support and component shims
• Security - Security model deep dive
• Troubleshooting - Common issues and solutions
• Contributing - Development setup and guidelines
• Architecture - Extension and webview architecture
• Examples - Working examples for Docusaurus, Starlight, Nextra, Next.js, PlantUML, Graphviz, lightbox/zoom, and more

Credits

Based on the original vscode-mdx-preview by Xiaoyi Chen, who created the original codebase, architecture, and UI.

License

GPL-3.0-or-later (in accordance with the original project)