Markdown plugins

[cbreeden]

A strategy for allowing users to install markdown-it plugins was discussed in #7656. This is an attempt to implement the ideas discussed there. I feel that the README describes the implementation well, so I'll just post it here. I would like to incorporate a few tests maybe, are there any ideas? So far, it seems to be working.

Using Markdown-it Plugins

To use a markdown-it plugin, goto the directory containing the markdown-it extension. This will be found in the extensions folder in your vscode installation. Install the markdown-it plugin as a node module. For example, to install the KaTeX markdown-it extension you would simply type:

npm install markdown-it-katex

Next, add the plugin into your settings configuration under the "markdown.plugs" namespace. This setting should contain a list for each markdown-it extension you wish to install. The list should contain an object describing the name of the module, a list of styles that your extension may require, and options that you wish to pass to your extension. For example, while installing the markdown-it-katex extension we would include this in your settings configuration:

    "markdown.plugins": [
        {
            "name": "markdown-it-katex",
            "styles": [
                "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.css"
            ],
            "options": { "throwOnError": false }
        }
    ]

The styles field can contain a filename or a URL. If the field is a file, file must be placed in the /media folder of the vscode markdown extension. And that's all there is to it. Enjoy!

[mention-bot]

By analyzing the blame information on this pull request, we identified @kieferrm and @jrieken to be potential reviewers

[msftclas]

Hi @cbreeden, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution!

In order for us to evaluate and accept your PR, we ask that you sign a contribution license agreement. It's all electronic and will take just minutes. I promise there's no faxing. https://cla.microsoft.com.

TTYL, MSBOT;

[msftclas]

@cbreeden, Thanks for signing the contribution license agreement so quickly! Actual humans will now validate the agreement and then evaluate the PR.

Thanks, MSBOT;

[rebornix]

Just curious, is it necessary to have separate styling for plugins?

[cbreeden]

Sorry for the delayed response. Do you mean to ask if plugins need stylesheets or if it's necessary to keep the stylesheet references with the plugin declarations in markdown.plugins? KaTeX for instance does need stylesheets, whether or not these should be declared here of in markdown.styles may be up to debate. I personally like having styles that are associate with plugins with their plugin declarations themselves, but I guess I don't mind either way.

I liked the idea of having a default folder for where we should lookup styles, which I opted for the 'media' folder in the Markdown extension. Using markdown.styles when providing a single filename like "styles.css", it appears that VSCode will only look in the root directory of the current project. This certainly isn't ideal for plugins, so the alternative would be to either provide a URL or a full filepath. As a user installing a markdown plugin, where do you think is a good place to put stylesheets for markdown plugins? I guess a more general question would be: where is a good place to configuration files for vscode extensions? Has this been done? Maybe we could do whatever they do for consistency?

[cbreeden]

I'm sorry, I know that I keep saying KaTeX this and KaTeX that, and I haven't considered if you were familiar with what that is. The KaTeX plugin is to allow math support for markdown, and I keep referencing it because it's one of the more complicated plugins you will find with respect to how styles need to be handled and that it outputs a hefty chunk of DOM to render the math for display. So I have been using this plugin mostly as a testing grounds. See #2273 for instance.

There is one more thing to consider. I'm not sure how to solve this problem yet. Some styles will want other things, like fonts or background images for instance. Something like this:

@font-family
  src: url('fonts/RequireFont.ttf');

Ideally you would also want a place where you can keep these requirements. Something like in the "media" folder for the markdown extension I was thinking. I'm not sure how to tell the browser this, as I think these relative paths will point to the relative path of "webview.html"?

[rebornix]

I got the idea that plugin may require specific styles and I'm Okay with that from code level. The only catch I can come up with is the order of styles injection. Now we have user styles array and plugin styles, what's the expected order? We can say any style in the user styles array will be injected the same way they are in the array but how about plugin styles? Are they before or after the user styles? This might be a problem when they have the same css selector. Other parts are all good to me.

Maybe we just need a clearer guidance for users.

[cbreeden]

Good point. with the current commit the order of the styles injects will be the same order as they are listed in the "markdown.styles" configuration, which occur after the default markdown styles from vscode. The order of the markdown plugins are also loaded in the same order as they are listed in the "markdown.plugins" configuration, which also occur after the default markdown plugins. Do you think this is sufficient flexibility? Should I add a remark in the README.md about this?

[rebornix]

So the sequence will be: default style, user style, default plugin, custom
plugin. Correct ne if I made any mistake. If not, you may want to make this
clear for users :)

cbreeden notifications@github.com于2016年6月22日周三 08:12写道：

In extensions/markdown/README.md
#7794 (comment):

+sh +npm install markdown-it-katex +
+
+Next, add the plugin into your settings configuration
+under the "markdown.plugs" namespace. This setting should contain a list for each markdown-it extension you wish
+to install. The list should contain an object describing the name of the module, a list of styles that your extentsion
+may require, and options that you wish to pass to your extension. For example, while installing the markdown-it-katex
+extension we would include this in your settings configuration:
+
+``` json

• "markdown.plugins": [

•    {
  

•        "name": "markdown-it-katex",
  

•        "styles": [
  

Good point. with the current commit the order of the styles injects will
be the same order as they are listed in the "markdown.styles"
configuration, which occur after the default markdown styles from vscode.
The order of the markdown plugins are also loaded in the same order as they
are listed in the "markdown.plugins" configuration, which also occur after
the default markdown plugins. Do you think this is sufficient flexibility?
Should I add a remark in the README.md about this?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/Microsoft/vscode/pull/7794/files/b7fdb0cf7e85d834251a97c843bf756b56ef8c51#r67975515,
or mute the thread
https://github.com/notifications/unsubscribe/AA1heCPQ_nTktCVgCH4jrL8tbJsLrsPcks5qOH35gaJpZM4I32wm
.

[cbreeden]

Oh, you are right, I made a mistake. The plugins do not overwrite previously loaded plugins even if they are already loaded, as an example:

var mdnh = require('markdown-it-named-headers');
var md = require('markdown-it')().use('mdnh').use('mdnh');

md.render('# Test')

will return <h1 id="test" id="test">Test</h1>. I will go ahead an do what you suggested below, make a builtInPlugins list and merge it with userPlugins as you have suggested and then clean up the README.md to clarify the order in which events occur and that the order may override other settings. Thanks for looking at this!

[cbreeden]

@rebornix had some good suggestions, like just placing styles in the "markdown.styles" file. I think this is fine, as I wasn't entirely happy with how the file handling was being done with previously. So I've updated the readme:

---

Using Markdown-it Plugins

To use a markdown-it plugin for markdown preview rendering, you will need to provide the name
and settings for each plugin in your "markdown.plugins" workspace configuration. An example
configuration is shown here:

    "markdown.styles": [ "file:///Path/To/katex.min.css" ],
    "markdown.plugins": [
        {
            "name": "markdown-it-katex",
            "options": { "throwOnError": false }
        }
    ]

This configuration will tell the markdown extension to load the plugin "markdown-it-katex" with the options
{ "throwOnError": false }. This particular plugin requires additional styling to work properly, so you can
place the references for these stylesheets in your "markdown.styles" workspace configuration. The stylesheet
in the "markdown.styles" may be either a URL, a file:///... or simply a filename like styles.css which
then should be placed in the root directory of your workspace.

Before the markdown extension can load markdown-it plugin properly, you must install the node package. You
can do this anywhere where the markdown extension can find your plugin. So you can for instance install
the package locally in the extensions/markdown folder using with

npm install markdown-it-katex

or globally with

npm install -g markdown-it-katex

---

Here it is in action:

Edit: Of course I meant 2\pi for integrating :)

[cbreeden]

@kieferrm seems pretty hard at work getting everything ready for the next release. I'm going to close this for now, and maybe reopen it later. It's a pretty trivial pull-request, so this can be easily reopened at any time.

Thanks @rebornix for taking a look at it, you had some good suggestions.

Just to recap the status of the pull-request for future reference:

• Put built in plugins into a builtInPlugins list, and then merge the list with the userPlugins. This allows users to override default plugins and their settings (if, for instance, they wanted to use a different hilighter).
• Add a remark to the README.md that userPlugins and styles can overwrite the default styles/plugins.