Markdown Preview Enhanced: VS Code Setup and PDF Export
November 11, 2026 · 11 min read
Markdown Preview Enhanced: Setup, PDF Export, Code Chunks and Slides
Markdown Preview Enhanced (MPE) is a free, open-source VS Code extension that adds a richer preview alongside the built-in one. It adds extra diagram engines, PDF, PNG and JPEG export, runnable code chunks and reveal.js slides. This walkthrough covers install, the settings that matter, each export route, and which syntax only works inside MPE.
What MPE Adds on Top of VS Code
MPE is written by Yiyi Wang (GitHub user shd101wyy) and released under the University of Illinois/NCSA Open Source License. Its rendering engine is a separate library called Crossnote. The old Atom package is no longer maintained. MPE also installs in VS Code for the Web, but features that call local programs, such as Chrome export and code chunks, need desktop VS Code.
Here's what you get on top of VS Code's own preview:
- More diagram types. Mermaid, PlantUML, Graphviz, WaveDrom, D2, TikZ, Vega and Vega-Lite, plus Kroki for many more.
- Export from the preview. HTML, PDF, PNG and JPEG through Chrome, PDF through Prince, and ebook or Pandoc output if those tools are installed.
- Code chunks. Fenced code that runs on your machine and writes its output into the preview.
- Slides. One Markdown file becomes a reveal.js presentation.
- File imports. Pull other Markdown files, CSVs, images or code into the current document.
If you're still choosing extensions, our VS Code Markdown extensions roundup compares MPE with the alternatives. For how previews work across GitHub, Obsidian and other apps, see our guide to previewing Markdown.
How to Use Markdown Preview Enhanced in VS Code
Open the Extensions view (Ctrl+Shift+X, or Cmd+Shift+X on a Mac), search for markdown-preview-enhanced and click Install. The publisher is Yiyi Wang and the extension ID is shd101wyy.markdown-preview-enhanced. On a locked-down machine, download the .vsix file from the project's GitHub releases and run Extensions: Install from VSIX... from the Command Palette.
The preview doesn't open by itself. Open a .md file, then right-click in the editor and pick Markdown Preview Enhanced: Open Preview to the Side. The keyboard is faster:
| Shortcut (Windows/Linux) | Mac | What it does |
|---|---|---|
| Ctrl+K V | Cmd+K V | Open the preview to the side |
| Ctrl+Shift+V | Cmd+Shift+V | Open the preview as a tab, not to the side |
| Ctrl+K Shift+L | Cmd+K Shift+L | Open a locked preview to the side |
| Ctrl+Shift+S | Ctrl+Shift+S | Sync preview and source position |
| Shift+Enter | Shift+Enter | Run the code chunk under the cursor |
| Ctrl+Shift+Enter | Ctrl+Shift+Enter | Run all code chunks |
| Esc (in the preview) | Esc (in the preview) | Toggle the sidebar table of contents |
Ctrl+K V is a chord: press Ctrl+K, let go, then press V. MPE binds Ctrl+Shift+V to its own preview, the same shortcut the built-in preview uses. By default it also hides VS Code's own preview buttons in the editor title bar, through the hideDefaultVSCodeMarkdownPreviewButtons setting.
A locked preview stays on one file while you edit another. That's handy when you keep a long spec open beside the section file you're working on.
Settings Worth Changing First: Themes, Math and Line Breaks
All MPE settings live under the markdown-preview-enhanced. prefix. Open your user settings.json and add the ones you want to change. Here are the defaults that matter most, with a couple of changes we'd make:
{
"markdown-preview-enhanced.previewTheme": "github-light.css",
"markdown-preview-enhanced.codeBlockTheme": "auto.css",
"markdown-preview-enhanced.mathRenderingOption": "KaTeX",
"markdown-preview-enhanced.mathInlineDelimiters": [["$", "$"]],
"markdown-preview-enhanced.mathBlockDelimiters": [["$$", "$$"]],
"markdown-preview-enhanced.mermaidTheme": "default",
"markdown-preview-enhanced.breakOnSingleNewLine": true,
"markdown-preview-enhanced.scrollSync": true
}
previewTheme offers more than a dozen themes, including github-dark.css, one-dark.css and solarized-light.css. codeBlockTheme set to auto.css picks a code style that matches the preview theme. mathRenderingOption accepts KaTeX, MathJax or None. breakOnSingleNewLine is on by default, so a single line break shows as a break, like a GitHub comment.
The two delimiter lines are our change. By default MPE also accepts \(...\) for inline math and \[...\] for display math. We prefer KaTeX with only the dollar delimiters, because those files render the same way on GitHub and in most other tools. Our Markdown math guide covers the syntax itself.
For anything deeper, run Markdown Preview Enhanced: Customize CSS (Global) to open a style.less file that styles the preview and its exports. Open Config Script (Global) opens config.js, where you can set KaTeX macros or Mermaid options. Per the docs, that file sits at %USERPROFILE%\.crossnote\config.js on Windows. On macOS and Linux it's under .crossnote in XDG_CONFIG_HOME, or in ~/.local/state/crossnote/. Both commands have Workspace versions too.
Diagrams and Math in the MPE Preview
Mermaid and math need no setup. Fence a diagram with mermaid and wrap math in dollar signs:
```mermaid
graph LR
A[Draft] --> B[Review]
B --> C[Publish]
```
$$
E = mc^2
$$
You get a three-box flowchart running left to right, then a centered equation. Change the diagram colors with mermaidTheme (default, dark or forest). The full Mermaid syntax lives in our Mermaid diagrams guide. To plot numbers as bar, line or pie charts, see our Markdown charts guide.
Other engines need more care. PlantUML runs the bundled plantuml.jar, so it needs Java, unless you point plantumlServer at a PlantUML server. D2 needs the d2 CLI on your PATH. Kroki diagrams are sent to the server in the krokiServer setting, which defaults to kroki.io. WebSequenceDiagrams needs network access to websequencediagrams.com. If a diagram is confidential, stick to Mermaid, Graphviz or a self-hosted server.
Only part of an MPE file is portable. The demo below is our Markdown to HTML converter. Its table, inline math and Mermaid diagram render in our editor's preview too, so you can check a document outside VS Code:
How Do You Export a PDF with Markdown Preview Enhanced?
Right-click inside the preview, not the editor. In recent versions, the preview's context menu has an Export submenu and an Open in Browser item. That gives you three PDF routes:
| Route | Menu path | Needs | Watch out for |
|---|---|---|---|
| Chrome (Puppeteer) | Export, then Chrome (Puppeteer), then PDF | Chrome installed | Page options go in front matter |
| Prince | Export, then PDF (Prince) | PrinceXML installed | The docs say it doesn't work with KaTeX or MathJax |
| Browser print | Open in Browser, then print to PDF | Any browser | Manual, and the browser adds its own margins |
The docs recommend the Chrome route, and so do we. It handles math and diagrams, and the same submenu exports PNG and JPEG. Export, then HTML saves a standalone page instead, in offline or CDN-hosted form. MPE finds Chrome on its own. If it can't, set chromePath to the browser's executable.
Page settings go in front matter at the top of the file:
---
puppeteer:
landscape: true
format: "A4"
export_on_save:
puppeteer: true
---
# Quarterly report
landscape and format pass straight to Puppeteer's PDF options. export_on_save with puppeteer: true writes a fresh PDF every time you save. Use puppeteer: ["pdf", "png"] to write both formats.
One surprise: printBackground is off by default, and the setting's own description says the export then uses the github-light theme. Turn it on, or set print_background: true in front matter, if you want a dark theme in your PDF.
Prince is worth it when you need print CSS such as @page sizes, which you add in style.less. For ways to make a PDF outside VS Code, see how to convert Markdown to PDF.
Running Code Chunks Without Opening a Security Hole
A code chunk is a fenced block with a cmd attribute after the language. Here are two that MPE runs on your machine:
```bash {cmd=true}
ls -1 *.md
```
```python {cmd=true output="markdown"}
print("| File | Lines |")
print("|---|---|")
print("| notes.md | 42 |")
```
The first lists the folder's Markdown files under the code block. The second prints a table, and output="markdown" makes the preview render it as a real table instead of plain text. Other output values are html, text, png and none. Put the cursor in a chunk and press Shift+Enter, or press Ctrl+Shift+Enter to run them all.
Nothing runs out of the box, though. Script execution is off by default, behind the enableScriptExecution setting. The official docs are blunt about why: with it on, opening a Markdown file that contains malicious code can compromise your machine.
We'd turn it on only in a trusted project's .vscode/settings.json, never in your user settings. Add cmd="node" or a full interpreter path when the language name isn't the command you want. Add hide=true to show only the output. For Python, matplotlib=true draws plots inline in the preview, and run_on_save=true reruns a chunk whenever you save.
Building reveal.js Slides with Slide Comments
MPE turns a file into a reveal.js deck when you separate slides with a slide comment. Size and theme go in a presentation block in the front matter:
---
presentation:
theme: moon.css
width: 1280
height: 720
---
<!-- slide -->
# Q3 Roadmap
<!-- slide -->
## What shipped
- PDF export
- Dark theme
The preview switches to slide mode and shows two slides with reveal.js controls. Without width and height, the docs list 960 by 700 as the default. The revealjsTheme setting sets a default theme for every deck, and the front matter overrides it per file.
This separator is specific to MPE. A plain reveal.js setup or Marp uses different markers, which our Markdown slides guide compares.
File Imports, TOC and Other MPE-Only Syntax
@import pulls another file into the preview at that spot:
@import "chapters/intro.md"
@import "data/results.csv"
@import "diagram.png" {width="300px"}
@import "src/app.py" {class="line-numbers"}
A Markdown file is inlined. A CSV becomes a table, an image is shown at the given width, and other files appear as code blocks. Run Markdown Preview Enhanced: Create TOC to write a table of contents into the file, which MPE updates on save while the preview is open.
Here's the limitation to plan around. Code chunks, @import, slide comments and the export front matter only mean something inside MPE. GitHub shows the import lines as plain text and the front matter as a table, and other renderers show them raw or drop them. Our editor's preview doesn't render any of this MPE-only syntax either. Keep READMEs and shared docs to portable Markdown: GFM tables, dollar-sign math and Mermaid fences. If you need file includes outside MPE, our AsciiDoc vs Markdown comparison covers a markup that has them built in.
Markdown Preview Enhanced FAQ
Markdown Preview Enhanced earns its place when a document needs more than a preview: PlantUML or Graphviz, a PDF built by Chrome, runnable chunks or a quick deck. Keep MPE-only syntax for files that stay in VS Code, and write anything you'll share in portable Markdown. To check that portable part away from VS Code, paste it into our online editor and compare the tables, math and diagrams.