Plugins

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.

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;

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.