Conventions for packaging plugins

[JimMadge]

Hi MyST Markdown/JupyterBook team,

I am writing a Myst Plugin which I would like to use in The Turing Way.

We would like to support others using and contributing to the plugin, and keep the plugin code independent of the book contents. It would be great if it could be installed as a dependency, in a similar way to Sphinx extensions for JB1.

Is there a convention for how to do this? (I'm not familiar with packaging Javascript).
I could publish to GitHub, NPM (or PyPI?); but then I'm not sure how to declare the plugin in myst.yml as that wants the plugin's path.

And additional complication, my plugin has a dependency on js-yaml.

[agoose77]

Hey @JimMadge

We don't have a strong standard on this. I created an example for a JS plugin that uses esbuild to bundle the plugin and its dependencies into a single file, and released on GH releases: https://github.com/myst-examples/js-plugin
This plugin can be consumed by URL from its release endpoint:

It's pretty simple to adapt that to TypeScript.

Curvenote have some examples of compiling TypeScript plugins, which are published to NPM.

I'd be tempted not to push for NPM publishing up-front, because it's more to handle (tokens, etc) than just pushing a release artifact.

[JimMadge]

This sounds ideal! Solves distribution and packaging with dependencies 🎉.

[stevejpurves]

Hi @JimMadge

Just to extend on @agoose77's examples:

The simplest js plugin can be a simple esm module, requiring no packaging: e.g. https://github.com/myst-ext/myst-ext-lorem/blob/main/src/lorem.ts

other lightweight bundler choices:

• tsup - e.g. discourse directive
• ncc - see example

As the plugin can be loaded from any URL, you can choose to gather/host plugins for your community anywhere.

[agoose77]

@stevejpurves I'd perhaps recommend against ncc, given the lack of major activity/releases. Thoughts?

[choldgraf]

This question and the answers from @stevejpurves and @agoose77 nerd-sniped me into improving our plugin docs, PR is here :-)

• Document plugin packaging and improve plugin docs #2100

[JimMadge]

That is really useful, thanks 🙏.