Markdown Extension

Markdown extensions allow you to extend and enhance Visual Studio Code’s built-in Markdown preview. This includes changing the look of the preview or adding support for new Markdown syntax.

Changing the look of the Markdown preview with CSS

Extensions can contribute CSS to change the look or layout of the Markdown preview. Stylesheets are registered using the markdown.previewStyles Contribution Point in the extension’s package.json:

  1. "contributes": {
  2.     "markdown.previewStyles": [
  3.         "./style.css"
  4.     ]
  5. }

"markdown.previewStyles" is a list of files relative to the extension’s root folder.

Contributed styles are added after the built-in Markdown preview styles but before a user’s "markdown.styles".

The Markdown Preview GitHub Styling extension is a good example that demonstrates using a stylesheet to make the Markdown preview look like GitHub’s rendered Markdown. You can review the extension’s source code on GitHub.

Adding support for new syntax with markdown-it plugins

The VS Code Markdown preview supports the CommonMark specification. Extensions can add support for additional Markdown syntax by contributing a markdown-it plugin.

To contribute a markdown-it plugin, first add a "markdown.markdownItPlugins" contribution in your extension’s package.json:

  1. "contributes": {
  2.     "markdown.markdownItPlugins": true
  3. }

Then, in the extension’s main activation function, return an object with a function named extendMarkdownIt. This function takes the current markdown-it instance and must return a new markdown-it instance:

  1. import * as vscode from 'vscode';
  3. export function activate(context: vscode.ExtensionContext) {
  4.   return {
  5.     extendMarkdownIt(md: any) {
  6.       return md.use(require('markdown-it-emoji'));
  7.     }
  8.   };
  9. }

To contribute multiple markdown-it plugins, return multiple use statements chained together:

  1. return md.use(require('markdown-it-emoji')).use(require('markdown-it-hashtag'));

Extensions that contribute markdown-it plugins are activated lazily, when a Markdown preview is shown for the first time.

The markdown-emoji extension demonstrates using a markdown-it plugin to add emoji support to the markdown preview. You can review the Emoji extension’s source code on GitHub.

You may also want to review:

Adding advanced functionality with scripts

For advanced functionality, extensions may contribute scripts that are executed inside of the Markdown preview.

  1. "contributes": {
  2.     "markdown.previewScripts": [
  3.         "./main.js"
  4.     ]
  5. }

Contributed scripts are loaded asynchronously and reloaded on every content change.

The Markdown Preview Mermaid Support extension demonstrates using scripts to add mermaid diagrams and flowchart support to the markdown preview. You can review the Mermaid extension’s source code on GitHub.