Plugins provide powerful ways to extend and customize MyST by adding directives and roles or specific transformations on the AST that can download or augment your articles and documentation. These plugins also support custom rendering and transformation pipelines for various export targets including React, HTML, LaTeX, and Microsoft Word.
Overview of a Plugin¶
Plugins are executable javascript code that can modify a document source. The supported plugin types are:
- directives
- Add or overwrite directives, which provide a “block-level” extension point.
- For example, create a
:::{proof}
extension that allows for numbered proofs. - roles
- Add or overwrite roles, which provide an inline extension point.
- For example, create a role for showing units,
{si}`4 kg per meter squared`
. - transforms
- These plugins transform the document source while it is rendered.
- For example, add metadata or transform a link to a DOI.
Planned - Not Yet Implemented
- renderers
- These plugins add handlers for various nodes when exporting to a specific format.
- For example, do something special for node in HTML, React, Microsoft Word, or LaTeX.
Creating a Plugin¶
To create a plugin, you will need a single Javascript file[1] that exports one or more of the objects above. For example, a simple directive that pulls a random image from Unsplash can be created with a single file that exports an unsplash
directive.
const unsplashDirective = {
name: 'unsplash',
doc: 'An example directive for showing a nice random image at a custom size.',
alias: ['random-pic'],
arg: { type: String, doc: 'The kinds of images to search for, e.g., `fruit`' },
options: {
size: { type: String, doc: 'Size of the image, for example, `500x200`.' },
},
run(data) {
const query = data.arg;
const size = data.options.size || '500x200';
const url = `https://source.unsplash.com/random/${size}/?${query}`;
const img = { type: 'image', url };
return [img];
},
};
const plugin = { name: 'Unsplash Images', directives: [unsplashDirective] };
export default plugin;
A plugin to add an unsplash
directive that includes a beautiful, random picture based on a query string.
This code should be referenced from your myst.yml
under the projects.plugins
:
project:
plugins:
- unsplash.mjs
Then start or build your document using myst start
or myst build
, and you will see that the plugin is loaded.
myst start
...
🔌 Unsplash Images (unsplash.mjs) loaded: 1 directive
...
You can now use the directive, for example:
:::{unsplash} misty,mountains
:::

If you change the source code you will have to stop and re-start the server to see the results.
The types are defined in myst-common
(npm, github) with the DirectiveSpec
and RoleSpec
being the main types to implement.