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 23 themes
• Preview Themes - 15+ 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
• 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 docs/frameworks.md 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 />

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 docs/configuration.md 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 docs/security.md for the full security model.

Extension Settings

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 docs/troubleshooting.md 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
• Examples - Working examples for Docusaurus, Starlight, Nextra, Next.js, PlantUML, Graphviz, 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)