MyST Transforms

# Overview

These transforms take AST from mystjs and turn it into usable forms, enforce document structure, or provide other utilities.

These utilities are available on npm:

npm install myst-transforms

You can use the plugins as follows:

import { unified } from 'unified';
import { mathPlugin } from 'myst-transforms';

unified()
.use(mathPlugin, { macros: {} }) // Add the plugin with any options
.run(tree); // Run the AST through the set of plugins

// The AST has now been modified in place.

## List of Transforms¶

Add headers to each admonition (callout), such as Note or Important.
Optionally replace the header with the first paragraph of text if it is all bold.
Blocks
Ensure that all blocks in a document are not nested.
Blockquotes
Change attributed blockquotes, those that include a single list item to a figure of kind quote, and add the attribution as a figure caption.
Caption
Ensure that figure captions are in paragraphs
Code
Audit code to ensure that languages are specified, or provide a default language
Ensure that python as a language is replaced from IPython3 or other kernal-like language specifiers.
CodeBlock
Codeblocks can live inside of figures, have captions and be references. Transformation ensures that this information isn't lost from the original parsing of AST.
Note: this should move into the parser in the future.
Footnotes
Pull the footnote definitions into a reference object.
HTML
Parse HTML nodes and replace their contents.
HTML Ids
Ensure that referenceable nodes have proper HTML Ids (start with a letter, no spaces or fancy characters)
HTML Ids are more strict than the internal labels used for cross-references, and this is up to the transform to provide, not the renderer.
Images
Add alt text to images if it is not defined, from the captions.
Keys
Add unique identifiers to each node, helpful for rendering as well as referring to a document in the wild. These are not aiming to be persisted across multiple builds of the document, for that you should use a label (and associated HTML Id).
Math
Use KaTeX to create and provide errors/warnings about math rendering.
Math Label
Parse latex to strip \label and simple equation environments from math, and put this in AST directly.
MyST Cleanup
A few utilities for lifting children and getting rid of some information about the parsed document from MyST. For example, the mystDirective and mystRole wrapper nodes are removed.
Targets
Propagate targets (i.e. (my-id)=) to the following node
A few of the plugins are exposed in a basicTransformationsPlugin does a number of the expected transformations without any user supplied options. See the code for exactly which plugins are included. If you are depending on this, ideally use the individual plugins directly, which will always provide options.