Make VS Code Markdown Preview match GitHub as closely as possible.
VS Code's built-in Markdown Preview is a general-purpose renderer, but what developers actually care about is how their documentation will look once it lands on GitHub. This project is not trying to create a GitHub-like theme. Its goal is to align VS Code preview output with GitHub's Markdown preview behavior and presentation as closely as possible.
That makes README writing, docs authoring, and general Markdown editing much more predictable: developers can edit and preview locally while seeing something close to the final result they expect on GitHub, instead of discovering layout or rendering mismatches only after pushing.
This project focuses on two practical outcomes:
- Align the rendering, spacing, and visual details of GitHub Markdown instead of inventing a separate lookalike theme
- Keep local preview and expected GitHub output as close as possible so documentation work needs less trial and error
- Keep
markdown-mermaiddiagrams on a matching light or dark theme when Mermaid theme sync is enabled
- Task Lists โ
- [x]and- [ ]render as GitHub-style disabled checkboxes. - Footnotes โ
[^1]references with automatic numbering, backrefs, and a footnotes section at the bottom. - Alerts โ
[!NOTE],[!TIP],[!IMPORTANT],[!WARNING], and[!CAUTION]render with proper icons and styling. - Emoji Shortcodes โ
:rocket:,:+1:,:tada:and thousands more, including both Unicode emoji and image-based custom emoji from GitHub. - HTML Image Path Rewriting โ absolute paths in HTML
<img>tags (/path/to/img) are rewritten to relative paths (./path/to/img), so project-local images work correctly in VS Code's webview preview.
9 built-in GitHub themes, covering light, dark, dimmed, high contrast, and colorblind-friendly variants:
| Light | Dark |
|---|---|
| Light | Dark |
| Light Protanopia & Deuteranopia | Dark Protanopia & Deuteranopia |
| Light high contrast | Dark high contrast |
| Light Tritanopia | Dark dimmed |
| Dark Tritanopia |
Two theme modes:
- Single โ always use one fixed theme.
- System โ follow the preview's light/dark color scheme, with separate themes for each.
Switch themes anytime via VS Code commands (Quick Pick) โ no need to open settings.
When githubMarkdown.mermaid.syncTheme is enabled, the extension updates the markdown-mermaid light/dark theme settings to match the active GitHub Markdown theme. It does not ship a Mermaid renderer or add a Mermaid dependency.
See CONTRIBUTING.md for development setup and guidelines.
This project is licensed under the terms of the MIT open source license.