Markdown Preview Extensions Exploration

[mjbvz]

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

[hoovercj]

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.

Does that mean user stylesheets/theme overrides are coming soon?

[mjbvz]

@hoovercj User stylesheets for the markdown preview is already supported: https://code.visualstudio.com/Docs/languages/markdown#_using-your-own-css

[hoovercj]

@mjbvz of course, sorry, I forgot the context and got excited about theme overrides. Ignore me :-)

[mjbvz]

Some feature requests that markdown extensions would cover:

#10367
#9982
#9136
#2273

[mjbvz]

Some prototype extensions:

https://github.com/mjbvz/vscode-markdown-emoji
https://github.com/mjbvz/vscode-markdown-katex
https://github.com/mjbvz/vscode-markdown-checkboxes
https://github.com/mjbvz/vscode-github-markdown-preview-style
https://github.com/mjbvz/vscode-markdown-mermaid

Thoughts on other prototypes to look into:

• highlight.js themes
• Follow up with https://github.com/goessner/mdmath

[h1romas4]

Hello.

It is a grate feature! Thank you.

I tried this feature and plugins, but it did not work.
Missing markdown.enableExperimentalExtensionApi in extensions/markdown/package.json?

• VSCode Version: Code - Insiders 1.11.0-insider (cc46bbf, 2017-03-31T14:08:17.917Z)
• OS Version: Windows_NT ia32 10.0.15063
• Extensions:

Extension	Author	Version
markdown-mermaid	bierner	0.0.1
path-intellisense	christian-kohler	1.2.0
vscode-eslint	dbaeumer	1.2.8
php-intellisense	felixfbecker	1.1.4
HTMLHint	mkaufman	0.3.3
PowerShell	ms-vscode	0.11.0

[mjbvz]

@h1romas4 It's still an experiment which is why the setting is not publicly documented yet. I've also republished the mermaid vsix. Please give it a try and let me know if you run into any issues: https://github.com/mjbvz/vscode-markdown-mermaid

[h1romas4]

@mjbvz Sorry, I was wrong. new vscode-markdown-mermaid is work! Thank you!

[davidanthoff]

This looks great!

I'd be interested in a slight variation of this: in the julia extension we support julia markdown files. They have the file ending .jmd. Ideally I would like to reuse the markdown preview for jmd files, but add in some custom extensions into that markdown preview that are only used for jmd files, not any other markdown files.

[mjbvz]

@davidanthoff Is this the project you are targeting https://github.com/mpastell/Weave.jl ?

[davidanthoff]

@mjbvz Yes, Weave.jl is the one. Essentially the markdown extension would detect code blocks in the markdown like this:

Here is some markdown.
```julia
plot(x,y)
```
More markdown

And then it could insert the results of that julia code into the markdown preview.

[mjbvz]

Thanks for the additional info @davidanthoff

This feature was not designed with that use case in mind, but I would be very interested to see if the new API would fit your needs as well. Perhaps you could try prototyping something and let me know what sort of problems you run into? The API is still experimental and could certainly be updated based on your feedback.

To get started, try taking a look at the prototype mermaid extension: https://github.com/mjbvz/vscode-markdown-mermaid/blob/master/index.js . This extension handles markdown code blocks such as:

```mermaid
...
```

and injects a script into the preview to actually render these as graphs and sequence diagrams. I imagine you should be able to do something similar.

Please let me know if you have any questions and please share any feedback about the new API

[d-kr]

Is it possible to add language server support?

[vstirbu]

Using your own CSS in markdown preview does not allow extension authors to provide theme specific stylesheets. Are there any plans to support this?

[mjbvz]

@vstirbu See the section on Changing the Styling of the Markdown Preview. Currently the css can be customized by light/dark/high-contrast

[mjbvz]

Keeping this experimental in May with VSCode 1.13. We'll reevaluate this again for the June sprint

I'm also planning to tweak the API slightly. The original proposed API defined style contributions using:

"contributes": {
     "markdown.preview": {
            "styles": ["./my_custom_style.css"],
            "scripts": ["./custom_script.js"]
         }
}

For consistency with other contributions, this will be changed to:

"contributes": {
     "markdown.previewStyles": [ "./my_custom_style.css"],
     "markdown.previewScripts": ["./custom_script.js"]
}

This will break some of the experimental extensions. I'll try to update the examples I've posted once the API change goes in

[davidanthoff]

@mjbvz I looked at this again. I think the biggest issue I have right now is that I actually don't want to modify the behavior of the preview for normal markdown files at all. I think really what I would need is an API exposed by the markdown preview that allows me to configure the markdown preview extension from my julia extension. For example, that API would have a function like addfiletype(filetype) that would allow my julia extension to tell the markdown extension to also handle *.jmd files. And then this API would allow me to configure which markdown extensions that I provide in the julia extension I want activated for *.jmd files, and maybe also allows me to e.g. configure markdown-it settings specifically for *.jmd files. So that would require that my julia extension can actually have some markdown extensions in it and exposed, but those should not be used when the markdown preview shows say a *.md file.

[mjbvz]

Good news, everyone! VSCode 1.15 insiders now has markdown extensions enabled by default.

The API has changed slightly since the initial proposal. The most up to date documentation is now in a pre-release version the VS Code docs: https://github.com/Microsoft/vscode-docs/blob/vnext/docs/extensionAPI/api-markdown.md

I've also tried to update most the example extensions to use the new API. These will be published to the marketplace after 1.15 ships

Please give the API a try and let me know if you run into any problems