Prototype Allowing Extensions to Extend the Builtin Markdown Extension by mjbvz · Pull Request #22421 · microsoft/vscode

mjbvz · 2017-03-10T21:01:14Z

Update
Switched over to use the pull model with the markdown extension exposing an API that other extensions can invoke. Also added an example extension to show how this API would work

Problem
There have been requests for adding new functionality to the markdown extension preview, such as supporting rendering of math or other syntax in the preview. The only current solution to this is create an extension that provides its own markdown preview. This results in inconsitent behavior with our markdown preview and is not a very scalable approach. We would like to find a way to allow users to add these extensions to our markdown preview without bundling lots of additional packages with vscode

Fix
Prototypes a new contribution point that extensions can use to extend the vscode markdown extension. Three types of extensions are possible: adding stypes to the preview, adding scripts to the preview, and extending the markdown it renderer.

My current approach defines the contributed markdown extensions in the package.json using a structure like this:

  "contributesTo": {
    "vscode.markdown": {
      "plugins": [
        "./out/math"
      ],
      "scripts": [],
      "styles": [
        "./media/math.css"
      ]
    }
  }

We could change the structure here. This design uses a pull model where markdown extensions are looked up by the vscode.markdown extension itself.

The other approach for extension registration would be to use a push model. This would have the vscode.markdown extension export an api that each markdown extension would invoke to register new scripts/styles/plugins. I may switch over to this model but was interested in seeing what a more declarative approach would look like. Let me know if you have any thoughts one way or the other.

The downside of allowing extensions like this is that they can completely change how the markdown preview looks and works. There is no well defined API for restricting what markdown extensions can do

mention-bot · 2017-03-10T21:01:16Z

@mjbvz, thanks for your PR! By analyzing the history of the files in this pull request, we identified @joaomoreno and @jrieken to be potential reviewers.

jrieken · 2017-03-13T07:45:04Z

Nice problem. The idea of the push model is surfaces in the fact that an extension can return its API from its activate call. Other extension can then take an extension-dependency, get the extension, and use its exports. This comment shows a sample of how things work. I think in general this model allows more degrees of freedom, like register callbacks that do something instead of just add static resources.

The pull model on the other hand looks simpler but also less powerful. Also, I am not sure if you can add more intelli-sense help to the package.json. Tho @aeschli will know

mjbvz · 2017-03-14T01:29:18Z

I've switched over to use the pull model, with the markdown extension exposing an API that other extensions can invoke. I also added an example extension that adds emoji support for markdown to show how this API works

aeschli · 2017-03-14T08:56:47Z

I'd prefer the original approach with the contributes section. I know we have the API to access other extensions, but going that approach has some problems:

Too tight coupling: Plugin will look for a specific extension (such as 'vscode.markdown') and will make assumptions on the shape of the API. But extensions should be replaceable and it would great if also other extensions can use the plugins.
Activation: Plugins need to know the activation points of the Markdown extension in order to register themselves at the right time

**Problem** There have been requests for adding new functionality to the markdown extension preview, such as supporting rendering of math or other syntax in the preview. The only current solution to this is create an extension that provides its own markdown preview. This results in inconsitent behavior with our markdown preview and is not a very scalable approach. We would like to find a way to allow users to add these extensions to our markdown preview without bundling the extensions in the preview itself. **Fix** Prototypes a new contribution point that extensions can use to extend the vscode markdown extension. Three types of extensions are possible: adding stypes to the preview, adding scripts to the preview, and extending the markdown it renderer. My current approach defines the contributed markdown extensions in the package.json using a structure like this: ``` "contributesTo": { "vscode.markdown": { "plugins": [ "./out/math" ], "scripts": [], "styles": [ "./media/math.css" ] } } ``` We could change the structure here. This design uses a pull model where markdown extensions are looked up by the vscode.markdown extension itself. The other approach for extension registration would be to use a push model. This would have the vscode.markdown extension export an api that each markdown extension would invoke to register new scripts/styles/plugins. I may switch over to this model but was interested in seeing what a more declarative approach would look like. Let me know if you have any thoughts one way or the other. The downside of allowing extensions like this is that they can completely change how the markdown preview looks and works. There is no well defined API for restricting what extensions can do like we have with VScode.

mjbvz · 2017-03-17T00:27:34Z

Thanks @aeschli. We discussed the benefits of either approach a little more at our Tuesday sitdown and ultimately came out slightly more in favor of using the API based approach. The main reason is that this fits into our existing extension model and it means we can treat these markdown extensions just like we would any other extension.

As for the two issue you bring up, take a look at the most recent change: it adds a new internal _markdown.onActivateExtensions command to trigger the activation of the markdown extensions. This way, the extensions themselves only have to know to activate on this command. I'm not entirely convinced this is a good solution, but it does work in my testing and avoids some of the problems you describe. It also would let us effectively version the markdown extension extensions. If we ever need to make a breaking API change, we could just introduce a new activation event such as _markdown.onActivateExtensions.2 that extensions would have to activate on instead

Just talked with @kieferrm and we're going to check in this work in it's current state so that extension developers can start playing around with it. I've added a undocumented markdown.enableExperimentalExtensionApi setting gate that must be set to enable this functionality, and we have not committed to any APIs or even to this feature yet, but I want to get something into the insiders builds so that developers can provide feedback.

Again, nothing is set in stone yet but using the extension API seems like the most promising approach at the moment. As always, please share any additional feedback or concerns that you have about the current approach and let me know if you feel something could be improved

aeschli · 2017-03-17T09:26:33Z

Neat trick with the command. You just need to hope that no one else calls that command :-)
Makes sense to experiment and gather experiences.

mjbvz · 2017-03-17T23:25:45Z

Hey @aeschli and @jrieken, after playing around with this prototype I've put together a new proposal for markdown extensions: https://github.com/mjbvz/vscode-markdown-emoji#api-proposal-take-two-not-yet-implemented

Take a look and let me know if you have any concerns or suggestions here. It combines some aspects of each of the original prototypes

msftclas added the cla-not-required label Mar 10, 2017

mjbvz self-assigned this Mar 10, 2017

mjbvz requested a review from kieferrm March 10, 2017 22:57

mjbvz force-pushed the prototype-md-extensions branch 2 times, most recently from 2757003 to ce8baef Compare March 14, 2017 01:06

mjbvz added 2 commits March 14, 2017 13:02

Use extensionDependencies

f254a50

mjbvz mentioned this pull request Mar 16, 2017

Extending VSCode's Builtin Markdown Preview goessner/mdmath#15

Closed

Remove example extension

d090c04

mjbvz force-pushed the prototype-md-extensions branch from ce8baef to d090c04 Compare March 16, 2017 20:57

Added gating and activation event

45815bf

mjbvz merged commit 09ec355 into microsoft:master Mar 17, 2017

github-actions bot locked and limited conversation to collaborators Mar 27, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prototype Allowing Extensions to Extend the Builtin Markdown Extension#22421

Prototype Allowing Extensions to Extend the Builtin Markdown Extension#22421
mjbvz merged 4 commits intomicrosoft:masterfrom
mjbvz:prototype-md-extensions

mjbvz commented Mar 10, 2017 •

edited

Loading

Uh oh!

mention-bot commented Mar 10, 2017

Uh oh!

jrieken commented Mar 13, 2017

Uh oh!

mjbvz commented Mar 14, 2017

Uh oh!

aeschli commented Mar 14, 2017

Uh oh!

mjbvz commented Mar 17, 2017 •

edited

Loading

Uh oh!

aeschli commented Mar 17, 2017

Uh oh!

mjbvz commented Mar 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

mjbvz commented Mar 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mention-bot commented Mar 10, 2017

Uh oh!

jrieken commented Mar 13, 2017

Uh oh!

mjbvz commented Mar 14, 2017

Uh oh!

aeschli commented Mar 14, 2017

Uh oh!

mjbvz commented Mar 17, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aeschli commented Mar 17, 2017

Uh oh!

mjbvz commented Mar 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mjbvz commented Mar 10, 2017 •

edited

Loading

mjbvz commented Mar 17, 2017 •

edited

Loading