Skip to article content

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:

Add or overwrite directives, which provide a “block-level” extension point.
For example, create a :::{proof} extension that allows for numbered proofs.
Add or overwrite roles, which provide an inline extension point.
For example, create a role for showing units, {si}`4 kg per meter squared`.
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 = `${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:

    - 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.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication