Writing using Markdown (Myst) Files

Writing using Markdown (Myst) Files#

The Executable Book Project has defined an extended markdown syntax called MyST.

Some benefits of MyST over RST are:

  1. syntax is easier to remember

  2. good support for markdown highlighting in many code editors

  3. less susceptible to issues with whitespace.

Some benefits of using Myst Markdown files over IPYNB files are:

  1. easier to manage version control

  2. simpler file format

Writing Environment - Code Editors#

Myst Markdown is another flavour of the commonly used markdown syntax that brings over some useful features from RestructuredText such as directives and roles. The syntax is an extension over commonmark markdown so many code editors that can highlight markdown can highlight myst (for the most part).

Syntax highlighting is useful as it helps identify issues in syntax, such as not properly closing some markup.

If you are using VSCode to edit a file there is a MyST Extension available to help with syntax highlighting, auto-completion, in-place directive lookups, and previews.

Converting to Jupyter Notebook#

You can also easily convert md to ipynb using jupytext

Using jupyterlab extensions#

Note

26-Jan-2023 This extension is currently in alpha stage of development, so you may run into some issues along the way. It also currently does not support extension directives to myst such as sphinx-exercise as this plugin is powered by mystjs

You can now use jupyterlab-mystjs to render myst markdown within the jupyter notebook environment.

You can find more information on the using jupyterlab-mystjs page

MyST Resources#

  1. MyST Syntax Guide