# Writing using Markdown (Myst) Files

The [Executable Book Project](https://executablebooks.org) has defined an extended markdown
syntax called [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html).

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](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) 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](converting/md-ipynb)

## 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](https://github.com/executablebooks/mystjs)
```

You can now use [jupyterlab-mystjs](https://github.com/executablebooks/jupyterlab-mystjs) to render `myst` markdown within the `jupyter` notebook environment. 

You can find more information on the [using `jupyterlab-mystjs` page](jupyterlab-myst)

## MyST Resources

1. [MyST Syntax Guide](https://myst-parser.readthedocs.io/en/latest/using/syntax.html)