Debug plugins

This section describes a few ways to debug MyST plugins.

Debug mode¶

You can run MyST in debug mode to print a lot more information about what happens under the hood. This is useful for printing status messages in your plugins for debugging purposes.

To run MyST in debug mode, use the --debug flag like so:

$ myst --debug start

Use console.log to debug JavaScript plugins¶

The easiest way to debug your MyST plugin is to use console.log statements in JavaScript to print the contents of variables in your plugin. This allows you to inspect things at build time.

For example, if you put the following in the run(data) function of a directive, it will show you the metadata in data as part of the output of myst build or myst start.

console.log(data);

Make sure to run MyST in debug mode.

You should see the contents of data printed in your MyST build log.

Show the full depth of a MyST object in JavaScript logs¶

console.log will only show you the first layer of depth, but you may want to inspect all layers of a MyST object or AST node. This command will display all layers of an AST node at once:

console.dir(node, { depth: null, colors: true });

Debug executable plugins by printing to stderr¶

Executable plugins are more complex to debug because of the need to send data back and forth with the MyST build process. Because MyST relies on reading stdout to retrieve the output of an executable plugin, we cannot debug with normal print statements.

Instead, print to stderr, which will still be displayed in MyST when run under debug mode.

For example, here’s how you’d print to stderr in Python:

import sys
print("A message to stderr.", file=sys.stderr)

Or if you wanted to prettify the output of a MyST object (e.g. in a directive) you could use a module like pretty print.

import sys
from pprint import pprint
pprint(data, stream=sys.stderr)

This will show up in your MyST build if you run MyST in debug mode.