--- title: JavaScript Plugins description: Plugins implemented in JavaScript are easily used across different projects, as they do not require any additional programs to be installed. --- JavaScript plugins are native MyST plugins, which are loaded as modules into the MyST engine. Transforms defined in these modules have access to helpful AST manipulation routines made available by MyST. Edits to JavaScript plugins have no effect during execution of a MyST build, instead the build must be restarted. (defining-a-new-directive)= ## Defining a new directive To create a plugin, you will need a single JavaScript file[^esm] that exports one or more of the objects above. For example, a simple directive that pulls a random image from [Unsplash](https://picsum.photos/) can be created with a single file that exports an `picsum` directive. [^esm]: The format of the JavaScript should be an ECMAScript modules, not CommonJS. This means it uses `import` statements rather than `require()` and is the most modern style of JavaScript. :::{literalinclude} picsum.mjs :label: picsum-js-source :caption: A plugin to add an `picsum` directive that includes a beautiful, random picture based on a size and optional ID string. ::: This code should be referenced from your `myst.yml` under the `projects.plugins`: ```{code} yaml :filename: myst.yml project: plugins: - picsum.mjs ``` Then start or build your document using `myst start` or `myst build`, and you will see that the plugin is loaded. ```text myst start ... 🔌 Lorem Picsum Images (picsum.mjs) loaded: 1 directive ... ``` You can now use the directive, for example: ```markdown :::{picsum} :size: 600x250 ::: ``` :::{picsum} :size: 600x250 ::: If you change the source code you will have to stop and re-start the server to see the results. Every field a directive or role can define is listed in [](./plugins-reference.md). ## Implementing a custom transform Directives can be used to extend MyST with rich structured content. However, sometimes we want to _modify_ the existing behavior of MyST. One of the ways to do this is by writing a custom transform. In this section, we'll implement a transform that replaces **bold** text with _emphasis_. First, let's define the transform :::{literalinclude} markup.mjs :caption: A plugin to add a transform that replaces strong nodes with emphasis nodes. ::: this code should be referenced from your `myst.yml` under the `projects.plugins`: ```{code} yaml :filename: myst.yml project: plugins: - type: javascript path: markup.mjs ``` then start or build your document using `myst start` or `myst build`, and you will see that the plugin is loaded. The `stage` field and the arguments a transform receives are described in [](#plugins:transform-spec). ```text myst start ... 🔌 Strong to emphasis (markup.mjs) loaded: 1 directive ... ``` you can now use the directive, for example: ```markdown I am **special bold text**, whilst I am **normal bold text** ``` I am **special bold text**, whilst I am **normal bold text** (plugins:multi-page)= :::{seealso} Aggregate information across multiple pages A transform runs on one page at a time, but a plugin can still collect information from every page in a project and render it in one place - for example, for a site-wide glossary or a list of figures. See the [multi-page plugin demo](https://github.com/myst-contrib/plugin-multi-page-demo) for a working example and a walk-through of the pattern. ::: ## Examples of plugins The documentation you're reading now defines several of its own plugins to extend MyST functionality. These are all registered in the documentation's [myst.yml configuration](myst.yml) with syntax like below: ```{literalinclude} myst.yml :start-at: plugins :end-before: error_rules ``` Each plugin is defined as a `.mjs` file in the same folder as the documentation's MyST content. Below is the contents of each file for reference. ::::{dropdown} Plugin: Latex rendering ```{literalinclude} latex.mjs ``` :::: ::::{dropdown} Plugin: Display an image ```{literalinclude} picsum.mjs ``` :::: ::::{dropdown} Plugin: Custom directive for documenting roles and directives ```{literalinclude} directives.mjs ``` :::: ::::{dropdown} Plugin: Render web template options as a table ```{literalinclude} templates.mjs ``` ::::