From #22836

Feature

Allow extensions to enhance to VSCode's builtin markdown preview, such as adding math support for example

Working Draft of API

Extensions can enhance VSCode's markdown preview by:

• Providing stylesheets for the preview page
• Providing markdown-it plugins that add support for new markdown syntax
• Provide scripts that run on the preview page

Changing the Styling of the Markdown Preview

To change the styling of markdown preview page, just add a markdown.preview entry to the contributes section of your extension's package.json, like so:

{
    "contributes": {
        "markdown.preview": {
            "styles": ["./my_custom_style.css"]
        }
    }
}

styles should be an array of extension relative paths to CSS files. These stylesheets will be included on the markdown preview page, and will be included after the default markdown preview stylings but before the user's custom stylesheets.

Using Markdown-It Plugins to Support New Markdown Syntax

To support new markdown syntax, first add markdown-it.plugins entry in the extension's package.json

{
    "contributes": {
        "markdown-it.plugins": true
    }
}

This tells VSCode that your extension provides markdown-it plugins and that it should be activated before the markdown preview is shown.

To register the plugins themselves, in your extension's activate function, just return an object with an extendMarkdownIt method. This method takes a markdown-it instance and must return a modified version of that instance.

export function activate(context: vscode.ExtensionContext) {
    return {
        extendMarkdownIt(md: any): any {
            return md.use(require('markdown-it-emoji'))
        }
    }
}

VSCode's markdown extension will invoke extendMarkdownIt when the markdown preview is shown for the first time.

🎵 Note: Your extension can still use other activation points that are triggered before a markdown preview is ever shown. The plugins entry only means that your extension will be activated when the preview is first shown if it has not already been activated previously.

Adding a Script that is Run in the Markdown Preview

If you need further customization, you can also inject a script into the markdown preview page:

{
    "contributes": {
        "markdown.preview": {
            "scripts": ["./my_custom_script.js"]
        }
    }
}

scripts should be an array of extension relative paths to javascript files. These scripts will be included on the markdown preview page. Scripts should only be used if a common mark plugin will not work