MyST Quickstart Tutorial

Installing MyST Command Line Tools

Work locally with MyST documents and notebooks

Objective

The goal of these quickstart tutorials are to get you up and running on your local computer 👩‍💻:

learn how to write MyST Markdown 🖊
export PDF, Word and $\LaTeX$ documents 📑
and create a website like this one 🌎

The tutorials will be brief on explaining MyST syntax, but we include an MyST Markdown Guide providing more depth on syntax and pointers to other pages.

Looking for JupyterBook docs?

The myst CLI is not the same as JupyterBook, which uses the Sphinx documentation engine! You can read about the history of mystmd development. The content that you build is compatible between tools in the MyST ecosystem, however, this tutorial focuses on the mystmd tools and CLI.

mystmd has capabilities beyond JupyterBook, for example exporting to scientific PDF documents, and you can use the two tools together! 💚

To follow along with this quickstart tutorial on your own computer, it is helpful if you have some familiarity with using the command line, as well as using a text editor and/or JupyterLab.

🛠 Throughout the tutorial, whenever you're supposed to do something you will see a 🛠

Installing the MyST Markdown CLI 📦¶

mystmd is a command line interface (CLI) that provides modern tooling for technical writing, reproducible science, and creating scientific & technical websites. To get started, install mystmd.

Prerequisites

You should have these programs installed:

Node.js version >=16.0.0
Node Package Manager (npm) version >=7.0.0
A code and notebook editor (VSCode is great, and we recommend Jupyter Lab for notebooks)

If the node ecosystem is new to you^[1], see our getting started guides for installing node.

Check your node installation greater than version 16 (see Installing NodeJS):

node -v
>> v16.18.1

🛠 Install the MyST command line tools:

npm install -g mystmd

If you have any problems, see installing MyST and or open an issue here. 🐛

Note: myst-cli is deprecated

In July 2023, we renamed the package to mystmd from myst-cli. Installing myst-cli will no longer create a myst command from your terminal. You can uninstall myst-cli using:

npm uninstall -g myst-cli

Updating MyST

There are new releases of the MyST Markdown CLI every few weeks, to update to the latest version of myst, use:

npm update -g mystmd

To get the latest templates, clean your templates directory with:

myst clean --templates

This will remove the _build/templates directory, which will be re-downloaded with the latest templates when you run myst start or myst build.

Download example content¶

We provide an example project that includes a few simple markdown files and some Jupyter Notebooks. In it's initial state, the project is not a good example of how to use MyST, but through the course of the tutorials you will correct that by improving the metadata, adding export targets, and creating a website!

🛠 Download the example content^[2], and navigate into the folder:

git clone https://github.com/executablebooks/mystmd-quickstart.git
cd mystmd-quickstart

Go through the tutorials 🚀¶

You are well on your way to getting started with myst the tutorials are written to go through in order, however, you can also jump in

🛠 Choose a quickstart tutorial to go on a mystical journey! 🃏 🎲

MyST Websites 🌎

Learn the basics of customizing a MyST Website, including sharing frontmatter between pages.

MyST Documents 📑

Learn the basics of MyST Markdown, and export to a Word document, PDF, and $\LaTeX$ !

MyST Markdown Guide 📖

See an overview of MyST Markdown syntax with inline demos and examples.

MyST Markdown

Quickstart Tutorials

MyST Websites