Better Markdown Preview

A better, theme-aware Markdown preview for Visual Studio Code.

Better Markdown Preview is an all-in-one replacement for the collection of extensions you would otherwise install to improve Visual Studio Code's built-in Markdown preview. It adds those features while keeping the native preview in place.

The extension adds:

• GitHub Flavored Markdown (GFM) task lists, literal autolinks, and tag filtering.
• A responsive H1-H3 table of contents with active-heading tracking.
• GitHub alerts, Terraform Registry callouts, footnotes, definition lists, and collapsible highlighted TOML and YAML frontmatter.
• Unicode emoji from named shortcodes such as :joy:, with optional emoticon shortcuts such as :).
• Responsive Pandoc-style columns.
• Locally bundled Mermaid rendering with a full-page viewer for zooming and panning around large diagrams.
• Code-block titles, line and word highlighting, line numbers, and diff annotations, while retaining VS Code's native highlighter.
• A layout driven by the active VS Code theme, with high-contrast and print styles.

Getting started

Install the extension from the registry used by your editor:

• Visual Studio Marketplace for Visual Studio Code
• Open VSX Registry for editors that use Open VSX

VS Code users can also install it from the command line:

code --install-extension jimeh.better-markdown-preview

Open a Markdown file and run Markdown: Open Preview or Markdown: Open Preview to the Side. No separate preview command or setup is required.

Compatibility note: Better Markdown Preview may conflict with other extensions that modify VS Code's Markdown preview. Disable or uninstall overlapping preview extensions to avoid duplicate rendering or unexpected behavior.

Extended syntax

TOML and YAML frontmatter

TOML frontmatter uses exact +++ delimiter lines at the start of a document; YAML uses ---. Both render expanded by default in a collapsible, syntax-highlighted code block without displaying their delimiter lines.

Columns

Columns use the supported Pandoc fenced-div subset:

:::: {.columns}
::: {.column width=40%}
Left column
:::
::: {.column}
Right column
:::
::::

Terraform Registry callouts

Terraform provider documentation callouts begin a paragraph with -> for a blue note, ~> for a yellow note, or !> for a red warning. A blank line ends the callout, and ordinary inline Markdown remains available inside it:

-> This is a **note**.

~> This note needs extra attention.

!> This is a warning.

Rich code blocks

Rich code metadata follows the language identifier:

```ts title="src/example.ts" {1,3-5} /needle/ showLineNumbers
const needle = true; // [!code ++]
```

Mermaid

Only an exact lowercase mermaid fence renders as a diagram. Mermaid is loaded from the extension package only when the document contains such a block; source remains visible if loading or rendering fails. Diagram surfaces are derived from the active editor background, foreground, and link accent colors. The Mermaid theme shift settings control how far fills and borders move toward those theme colors.

Emoji

Named emoji shortcodes render as Unicode emoji in ordinary Markdown text and link labels, but remain literal in inline and block code. Emoticon shortcuts are available separately and disabled by default.

Settings

Configure Better Markdown Preview at user or workspace scope. Boolean features are enabled by default except emoticon shortcuts; Mermaid theme shifts are percentages from 0 to 100:

Disabling a rendering feature stops Better Markdown Preview from handling that syntax and delegates it to VS Code or another Markdown extension. It does not force the syntax to remain literal. Theme integration, accessibility, overflow handling, print safety, and GFM tag filtering remain enabled because they apply to every preview.

Development

mise installs the locked runtime and validation tools. The project uses three-day release-age policies for Mise tools and pnpm dependencies.

mise run setup
mise run check
mise run verify

Use mise tasks to list all available tasks. Common development commands are:

• mise run dev watches the desktop, web, preview runtime, Mermaid, CSS, and TypeScript targets.
• mise run check runs formatting, linting, type checks, and unit tests.
• mise run lint runs native and type-aware Oxlint, Stylelint, and Markdownlint.
• mise run test:coverage enforces all-files V8 coverage floors.
• mise run test:desktop exercises the engine floor and stable desktop hosts.
• mise run test:web:stable exercises stable VS Code for the Web in Chromium after mise run test:hosts:prepare.
• mise run package:validate builds and inspects the VSIX.
• mise run release:check exercises versioning, notes, outputs, and workflow contracts without publishing.
• mise run verify runs all local checks expected before handoff.

See Architecture and Testing for the contracts those commands enforce. See Releases for the automated versioning, publication, and recovery contract.

License

Better Markdown Preview is available under the MIT License.