There is no “official” way to distribute MyST plugins. However, you can use common workflows in the JavaScript ecosystem to distribute your plugins so that others can use them. This page documents a few of them.
Distribute plugins as a single .mjs file if they have no dependencies¶
If your plugin doesn’t require any extra dependencies, then you can distributed it as a single .mjs file written in JavaScript. You can then use it locally or distribute it via a URL.
See JavaScript Plugins for several example plugins written as individual .mjs files with no dependencies.
Package plugins into a single ESM file if they have dependencies¶
If your plugin has other dependencies that it needs to package with the plugin, you can do so using the ECMAScript Modules standard for packaging and distributing JavaScript. The sections below describe how to do so.
Use a builder to build an ESM package¶
There are several “builders” in the JavaScript ecosystem that make it easy to quickly bundle JavaScript in distributable packages. The resulting artifact can then be shared directly, or published to a package registry like NPM.
We recommend esbuild.
Other JavaScript bundlers¶
There are a few other bundlers in the JavaScript ecosystem, which you may use to package MyST plugins if you prefer. We share them in case you don’t want to use esbuild for some reason (but for most people, esbuild should be just fine).
Distribute your plugin via a URL¶
The easiest way to distribute your plugin is via an accessible URL that points to the bundled file that you’ve created.
Then you can configure myst.yml to use the URL in your plugin.
For example, you can use GitHub releases to publish your built plugin as an artifact attached to a release. This will create a persistent URL that you can point to in your myst.yml build.
