Markdown View Toggle

A focused all-in-one Markdown extension for VS Code: toggle between source / rendered / split views in one click, preview your Markdown in GitHub's actual styles (7 theme variants, accessibility variants included), render task lists, emoji, admonition callouts, and Mermaid diagrams in the preview, and export to HTML, PDF, PNG, or JPEG with one command.

Inspired by Warp for the toggle feel and by bierner.markdown-preview-github-styles for the GitHub theming. Built for users who write a lot of Markdown and don't want to install five separate extensions to get a complete experience.

Quickstart (30 seconds)

Install — see Installation below
Open any .md file in VS Code
Look at the top-right of the tab — you'll see three icons:
- </> Source — raw markdown
- 👁 Preview — rendered preview (GitHub-styled)
- ▢│▢ Split — both at once, side-by-side
Click any of them to switch. Press Ctrl+Alt+M (Mac: Cmd+Alt+M) to cycle through them.
Look at the bottom-right status bar for live indicators of your current view mode, the active GitHub theme, and an Export button.

That's the whole tour. The rest of this README is reference material.

Installation

VS Code (official Microsoft build)

In VS Code:

Press Ctrl+Shift+X (Mac: Cmd+Shift+X) to open the Extensions panel
Type Markdown View Toggle in the search box
Click Install on the result by YetesfaAlemayehu

Or from the command palette:

ext install YetesfaAlemayehu.md-view-toggle

Or via the CLI:

code --install-extension YetesfaAlemayehu.md-view-toggle

Cursor, VSCodium, Gitpod, Theia (Open VSX users)

The same search and ext install command work in any editor that supports the Open VSX registry.

Manual install from `.vsix`

Grab md-view-toggle-X.Y.Z.vsix from the GitHub releases page and install it:

code --install-extension md-view-toggle-X.Y.Z.vsix

Or in VS Code: Ctrl+Shift+P → Extensions: Install from VSIX… → pick the file.

After installing, reload VS Code (Developer: Reload Window from the palette) — once. After that, the extension activates automatically the first time you open any .md file.

What you get

After installing, every Markdown file gets:

Where	What
Editor title bar (top-right of the `.md` tab)	3 icons for Source / Rendered / Split
Bottom status bar	3 items: current view mode, GitHub theme picker, Export button
Command Palette (`Ctrl+Shift+P`)	12 new commands under the `Markdown:` prefix
Right-click menu on `.md` files	Markdown: Export… entry
Markdown preview itself	GitHub-themed CSS, task lists, emoji, admonition blocks, Mermaid diagrams
Settings	13 new options under the `mdViewToggle.*` namespace
Keyboard	`Ctrl+Alt+M` / `Cmd+Alt+M` to cycle view modes

How to use each feature

1. Switch view modes

The whole reason this extension exists.

Three ways to switch:

Click one of the three icons in the top-right of the .md tab title bar
Click the status-bar mode item (bottom-right, shows $(code) Source / $(preview) Rendered / $(layout-sidebar-right) Split) — each click cycles to the next mode
Press Ctrl+Alt+M (Mac: Cmd+Alt+M) — same cycle, from the keyboard

Per-file memory: whichever mode you last picked for a given file is restored automatically the next time you open it (this session and across reloads, scoped to the current workspace).

Example flow:

1. Open notes.md → opens as Source (default)
2. Click the preview icon → switches to Rendered
3. Close the tab
4. Re-open notes.md → automatically opens as Rendered (remembered)
5. Click the split icon → switches to Split view
6. Close, re-open → opens as Split (remembered)

2. Auto-open important documents as rendered

By default, the following filenames open in Rendered view the first time you touch them per workspace session (you usually want to READ them, not edit them):

README.md
CHANGELOG.md
LICENSE.md
CONTRIBUTING.md
CODE_OF_CONDUCT.md

This is overridden the moment you click the Source icon — your manual choice always wins.

To customize the list, set mdViewToggle.autoOpenRenderedFor in settings.json:

{
  "mdViewToggle.autoOpenRenderedFor": [
    "README.md",
    "CHANGELOG.md",
    "ROADMAP.md",
    "NOTES.md"
  ]
}

To disable the feature entirely:

{
  "mdViewToggle.autoOpenRenderedFor": []
}

Match is case-insensitive on the file's basename. Globs are not supported in this list — for that, use the workspace command below.

3. Render every workspace `.md` as rendered (batch)

If you have a docs/ folder you mostly read rather than edit, you can mark every .md in the workspace to open in rendered view by default.

Press Ctrl+Shift+P to open the Command Palette
Type Markdown: Set All Workspace .md to Open as Rendered
A notification tells you how many files were marked (capped at 50; re-run to process more)

Each marked file remembers its preference per-workspace. Clicking the Source icon on any one of them overrides that file's preference.

4. Switch the GitHub theme variant

By default, the preview uses an Auto GitHub theme that follows your VS Code color theme (light when VS Code is light, dark when VS Code is dark). To pick a specific variant:

Click the GitHub: Auto (light) item in the status bar (bottom-right)
A quick-pick opens with 7 variants:

Variant	When to pick it
Auto	You want light/dark to follow VS Code automatically (default)
Light	Force GitHub light regardless of editor theme
Dark	Force GitHub dark regardless of editor theme
Dark Dimmed	Slightly softer contrast than full dark — easier on tired eyes
Dark High Contrast	Maximum legibility for accessibility
Dark Colorblind	Protanopia & Deuteranopia-friendly palette (dark)
Light Colorblind	Protanopia & Deuteranopia-friendly palette (light)

Your choice is persisted in your workspace settings. To set it programmatically:

{
  "mdViewToggle.githubTheme": "dark_dimmed"
}

Under the hood: Auto is wired via VS Code's markdown.previewStyles contribution. Picking a non-Auto variant writes a path to that variant's CSS into your workspace's markdown.styles setting. Picking Auto again clears that entry.

5. Use preview enhancements

The preview gets four extra rendering features beyond what VS Code's built-in markdown does. All are on by default and toggleable in settings.

GitHub-style task lists

Write:

- [ ] Buy groceries
- [x] Walk the dog
- [ ] Write the report

Preview renders these as actual checkboxes (read-only — they don't toggle when you click in the preview).

Toggle off: "mdViewToggle.preview.taskLists": false

Emoji shortcodes

Write:

:rocket: Ship it!
:warning: Heads up
:smile: :coffee: :computer:

Preview renders the full set of GitHub-flavored emoji shortcodes.

Toggle off: "mdViewToggle.preview.emoji": false

Admonition callout blocks

Write:

::: warning
Don't run this in production
:::

::: tip
The `-f` flag forces an overwrite
:::

::: note
This API was deprecated in v2.0
:::

::: danger
This will delete data
:::

::: info
Compatible with Node 18+
:::

Each block renders as a styled callout (color and icon vary by class). Five types supported: warning, note, tip, danger, info.

Toggle off: "mdViewToggle.preview.containers": false

Mermaid diagrams

Write a fenced code block with mermaid as the language:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Don't]
```

Preview renders an SVG diagram. The Mermaid library is loaded from https://unpkg.com/mermaid/dist/mermaid.min.js by default — requires an internet connection on first render per session.

Offline / self-hosted setups: change the URL via mdViewToggle.preview.mermaidServer. Toggle the feature off entirely with "mdViewToggle.preview.mermaid": false.

6. Export to HTML / PDF / PNG / JPEG

Three ways to trigger an export:

Via the Export status-bar item (easiest)

Open the .md file
Click the $(export) Export item in the bottom status bar
A quick-pick opens — choose HTML, PDF, PNG, JPEG, or All formats
The exported file is saved next to your source .md (or in your configured output directory)
A notification appears with the path and an Open Folder button

Via the Command Palette

Ctrl+Shift+P → type any of:

Markdown: Export… (picker, same as the status-bar item)
Markdown: Export as HTML
Markdown: Export as PDF
Markdown: Export as PNG
Markdown: Export as JPEG
Markdown: Export as HTML, PDF, PNG, and JPEG

Via right-click

Right-click any .md file in the Explorer panel or inside the editor — pick Markdown: Export….

Chromium download (first time only)

PDF, PNG, and JPEG export need a headless Chromium browser. The extension tries to find one in this order:

The path in your mdViewToggle.export.executablePath setting, if you've set it
An installed Google Chrome, Microsoft Edge, or Chromium on your system
A managed Chromium that the extension downloads on first use (~150 MB, one-time per machine)

The download happens automatically the first time you trigger a PDF/PNG/JPEG export. You'll see a notification:

Downloading Chromium for PDF/image export (~150 MB, one-time) — 47%

After that, every subsequent export is fast and offline. The download is stored in VS Code's per-extension global storage (the path is OS-specific; see Troubleshooting).

If you already have Chrome or Edge installed, no download happens at all.

Customize the PDF output

{
  "mdViewToggle.export.pdfFormat": "Letter",          // or A3, A4, A5, Legal, Tabloid
  "mdViewToggle.export.pdfMargin": "2cm",             // uniform; units: mm, cm, in, px
  "mdViewToggle.export.pdfDisplayHeaderFooter": true  // page number + filename
}

Customize the image output

{
  "mdViewToggle.export.imageQuality": 80    // JPEG quality 0-100; PNG ignores this
}

Where do exports go?

By default, into the same folder as the source .md file, with the same basename.

docs/
├── api.md
└── api.pdf       ← exported here

To override, set mdViewToggle.export.outputDirectory:

{
  // Absolute path
  "mdViewToggle.export.outputDirectory": "/Users/yetesfa/Documents/exports",

  // Relative to workspace root
  "mdViewToggle.export.outputDirectory": "build/docs",

  // Relative to your home directory
  "mdViewToggle.export.outputDirectory": "~/markdown-exports"
}

All commands

Every command is available from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

Command	Default keybinding
`Markdown: Show Rendered`	—
`Markdown: Show Default (Source)`	—
`Markdown: Show Split View (Source + Preview)`	—
`Markdown: Toggle View (Source → Rendered → Split)`	`Ctrl+Alt+M` / `Cmd+Alt+M`
`Markdown: Set All Workspace .md to Open as Rendered`	—
`Markdown: Pick GitHub Preview Theme`	—
`Markdown: Export…`	—
`Markdown: Export as HTML`	—
`Markdown: Export as PDF`	—
`Markdown: Export as PNG`	—
`Markdown: Export as JPEG`	—
`Markdown: Export as HTML, PDF, PNG, and JPEG`	—

To rebind Ctrl+Alt+M (or add shortcuts to any other command): File → Preferences → Keyboard Shortcuts, search "Markdown View Toggle", click the pencil icon.

All settings

All settings live under the mdViewToggle.* namespace. Open them via: File → Preferences → Settings, then search mdViewToggle — or edit settings.json directly.

View-toggle behavior

Setting	Default	Description
`mdViewToggle.autoOpenRenderedFor`	5 doc filenames (see above)	Filenames (basename, case-insensitive) that auto-open in rendered view. Set to `[]` to disable.

GitHub theme

Setting	Default	Description
`mdViewToggle.githubTheme`	`"auto"`	One of `auto`, `light`, `dark`, `dark_dimmed`, `dark_high_contrast`, `dark_colorblind`, `light_colorblind`. Easier to set via the status-bar picker.

Preview enhancements

Setting	Default	Description
`mdViewToggle.preview.taskLists`	`true`	Render `- [ ]` / `- [x]` as checkboxes.
`mdViewToggle.preview.emoji`	`true`	Render `:smile:` shortcodes as emoji.
`mdViewToggle.preview.containers`	`true`	Render `::: warning … :::` blocks as styled admonitions.
`mdViewToggle.preview.mermaid`	`true`	Render Mermaid diagrams from ```mermaid blocks.
`mdViewToggle.preview.mermaidServer`	unpkg.com CDN	URL of the Mermaid library. Override for offline / self-hosted setups.

Export

Setting	Default	Description
`mdViewToggle.export.outputDirectory`	`""` (same folder as source)	Where to save exports. Absolute, workspace-relative, or `~/` paths supported.
`mdViewToggle.export.executablePath`	`""`	Path to a specific Chrome/Edge/Chromium executable. Empty = auto-detect.
`mdViewToggle.export.pdfFormat`	`"A4"`	One of A4, A3, A5, Letter, Legal, Tabloid.
`mdViewToggle.export.pdfMargin`	`"1cm"`	Uniform page margin (units: mm, cm, in, px).
`mdViewToggle.export.pdfDisplayHeaderFooter`	`true`	Show page number and filename in PDF header/footer.
`mdViewToggle.export.imageQuality`	`90`	JPEG quality 0-100. PNG ignores this.

Example: my preferred setup

{
  "mdViewToggle.autoOpenRenderedFor": ["README.md", "CHANGELOG.md"],
  "mdViewToggle.githubTheme": "auto",
  "mdViewToggle.export.outputDirectory": "~/Documents/markdown-exports",
  "mdViewToggle.export.pdfFormat": "Letter",
  "mdViewToggle.export.pdfMargin": "2cm",
  "mdViewToggle.preview.mermaid": true,
  "mdViewToggle.preview.containers": true
}

Troubleshooting

"The icons aren't showing up in the title bar"

Reload VS Code once after install (Ctrl+Shift+P → Developer: Reload Window). The icons appear in any .md editor tab. If they still don't show, check that resourceExtname == .md matches your file — the file extension must be exactly .md (not .markdown or other variants).

"The status bar items are missing"

They only appear when an .md file or its preview is the active editor. Switch to a markdown file and they should appear in the bottom-right. If the status bar is hidden entirely, enable it via View → Appearance → Status Bar.

"The Mermaid diagrams aren't rendering"

The default mermaidServer URL requires internet access. If you're offline or behind a strict proxy:

Download mermaid.min.js from https://unpkg.com/mermaid/dist/mermaid.min.js
Host it somewhere accessible to your VS Code (or on localhost)
Set mdViewToggle.preview.mermaidServer to the new URL

Or disable Mermaid entirely: "mdViewToggle.preview.mermaid": false.

"The PDF export is downloading a huge file"

That's the managed Chromium binary (~150 MB), needed because PDF/PNG/JPEG export requires a headless browser. It's a one-time download per machine. To skip it, install Chrome, Edge, or Chromium system-wide — the extension will detect and use it automatically.

To use a specific browser you already have:

{
  // macOS example
  "mdViewToggle.export.executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",

  // Linux example
  "mdViewToggle.export.executablePath": "/usr/bin/chromium",

  // Windows example (note doubled backslashes)
  "mdViewToggle.export.executablePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
}

"Where is the downloaded Chromium stored?"

Inside VS Code's global storage for this extension:

OS	Path
Windows	`%APPDATA%\Code\User\globalStorage\yetesfaalemayehu.md-view-toggle\chromium\`
macOS	`~/Library/Application Support/Code/User/globalStorage/yetesfaalemayehu.md-view-toggle/chromium/`
Linux	`~/.config/Code/User/globalStorage/yetesfaalemayehu.md-view-toggle/chromium/`

To force a re-download, delete that folder and trigger an export again. (Replace Code with Code - Insiders or VSCodium for those builds.)

"The PDF rendering looks different from the preview"

The export pipeline uses the same Markdown rendering and the same GitHub CSS as the preview, so output should match closely. Differences usually come from:

Mermaid not rendering — the export waits for networkidle to load the Mermaid library; if your network is slow it may time out. Try again, or disable Mermaid for export-heavy workflows.
Custom markdown.styles entries — those apply to the preview but are NOT auto-included in the export. If you need them in the export, paste their CSS into a markdown-pdf.css and reference it manually (planned for a future version).

"I want to disable a feature without uninstalling"

Every preview enhancement and the export pipeline can be selectively disabled in settings — see the All settings section. To stop the GitHub theming entirely, currently you'd need to uninstall the extension (the always-on auto.css is a feature, not a bug — but if there's demand I'll add a disable flag in a future version).

Something else is broken

Open an issue at github.com/yetesfa/Markdown-View-Toggle/issues. Include:

Your VS Code version (Help → About)
Your OS
What you did
What you expected vs. what happened
The relevant mdViewToggle.* settings

FAQ

Q: Why not just use bierner.markdown-preview-github-styles for theming and yzane.markdown-pdf for export? A: You can! They're both excellent. This extension is an opinionated all-in-one for users who'd rather install one thing and have a complete experience. We don't compete on advanced features — we compete on coherence (consistent UI, single settings namespace, shared rendering pipeline between preview and export).

Q: Will this extension keep up with GitHub's design changes? A: The CSS comes from github-markdown-css, which is actively maintained and tracks GitHub's actual styles. We bump our copy when major changes ship.

Q: Does it work in Cursor / VSCodium / Gitpod? A: Yes — all features work in any VS Code-compatible editor. Install from Open VSX with the same name.

Q: Can I open .markdown files instead of .md? A: The title-bar icons and right-click export menu match on .md specifically. The commands work on any Markdown file via the Command Palette. Future versions may broaden the match.

Q: Does the extension upload anything? A: No. Everything happens locally. The Mermaid library is fetched from a CDN at render-time (or your configured URL) — that's the only network activity, and it's optional.

Q: I want to contribute / customize / fork. A: Source is at github.com/yetesfa/Markdown-View-Toggle, MIT licensed. PRs welcome.

Credits

github-markdown-css by Sindre Sorhus (MIT) — the CSS that makes everything look like GitHub
markdown-it + markdown-it-task-lists + markdown-it-emoji + markdown-it-container — preview enhancements
mermaid — diagram rendering
puppeteer-core + @puppeteer/browsers — headless Chromium for export
bierner.markdown-preview-github-styles — inspiration for the GitHub theming approach
yzane.markdown-pdf — inspiration for the export pipeline
Warp — inspiration for the one-click view toggle UX

Markdown View Toggle

Yetesfa Alemayehu

Markdown View Toggle

Quickstart (30 seconds)

Installation

VS Code (official Microsoft build)

Cursor, VSCodium, Gitpod, Theia (Open VSX users)

Manual install from .vsix

What you get

How to use each feature

1. Switch view modes

2. Auto-open important documents as rendered

3. Render every workspace .md as rendered (batch)

4. Switch the GitHub theme variant

5. Use preview enhancements

GitHub-style task lists

Emoji shortcodes

Admonition callout blocks

Mermaid diagrams

6. Export to HTML / PDF / PNG / JPEG

Via the Export status-bar item (easiest)

Via the Command Palette

Via right-click

Chromium download (first time only)

Customize the PDF output

Customize the image output

Where do exports go?

All commands

All settings

View-toggle behavior

GitHub theme

Preview enhancements

Export

Example: my preferred setup

Troubleshooting

"The icons aren't showing up in the title bar"

"The status bar items are missing"

"The Mermaid diagrams aren't rendering"

"The PDF export is downloading a huge file"

"Where is the downloaded Chromium stored?"

"The PDF rendering looks different from the preview"

"I want to disable a feature without uninstalling"

Something else is broken

FAQ

Credits

License

Manual install from `.vsix`

3. Render every workspace `.md` as rendered (batch)