Working with MyST Websites

Create a website like this one

πŸ›  Throughout the tutorial, whenever you're supposed to do something you will see a πŸ› 

πŸ›  Install the MyST Markdown CLI

πŸ›  Install the MyST command line tools, with node greater than version v16:

npm install -g mystmd
Need more help? See MyST Installation Quickstart

See the first quickstart tutorial for installation walk-through and installation prerequisites.

πŸ›  Download quickstart content

We are going to download an example project that includes a few simple markdown files and some Jupyter Notebooks. Our goal will be to try out some of the main features of mystmd to create a website like this one, improve the structure of the metadata, share it between pages, and improve the website theme.

πŸ›  Download the example content, and navigate into the folder:

git clone
cd mystmd-quickstart

Initialize MyST πŸš€ΒΆ

Next we will create a myst.yml configuration file that is required to render your project.

πŸ›  Run myst

The myst command is a shortcut for myst init, which has a few more options for writing specific parts of the configuration file and a table of contents for your site.

> myst

Welcome to the MyST Markdown CLI!! πŸŽ‰ πŸš€

myst init walks you through creating a myst.yml file.

You can use myst to:

 - create interactive websites from markdown and Jupyter Notebooks πŸ“ˆ
 - build & export professional PDFs and Word documents πŸ“„

Learn more about this CLI and MyST Markdown at:

πŸ’Ύ Writing new project and site config file: myst.yml

πŸ›  When prompted, type Yes to install and start the default theme (takes about 15 seconds)

? Would you like to run "myst start" now? Yes

If you cancelled the command, you can start the server with myst start. Starting the server requires a theme, this will download the default book-theme, which you can change later. The theme will now install using node and npm, this can take up to a minute the first time, and then will be cached in the _build/templates directory.

πŸ• Fetching template metadata from
πŸ’Ύ Saved template to path _build/templates/site/myst/book-theme
‡️ Installing web libraries (can take up to 60 s)
πŸ“¦ Installed web libraries in 13 s
πŸ“– Built interactive-graphs.ipynb in 21 ms.
πŸ“– Built in 32 ms.
πŸ“– Built in 35 ms.
πŸ“š Built 3 pages for myst in 82 ms.

  ✨✨✨  Starting Book Theme  ✨✨✨

⚑️ Compiled in 524ms.

πŸ”Œ Server started on port 3000!  πŸ₯³ πŸŽ‰

  πŸ‘‰  http://localhost:3000  πŸ‘ˆ

πŸ›  Open your web browser to http://localhost:3000[1]

The example site in this tutorial only has three pages and by default the page is seen in FigureΒ 1, which has minimal styles applied to the content.

The myst theme for the page without any changes made.

Figure 1:The myst theme for the page without any changes made.

Folder StructureΒΆ

If you are using a text editor, for example VSCode, open up the folder to explore the files:

  β”œβ”€β”€ πŸ†• _build
  β”‚   β”œβ”€β”€ exports
  β”‚   β”œβ”€β”€ site
  β”‚   β”‚   β”œβ”€β”€ content
  β”‚   β”‚   β”œβ”€β”€ public
  β”‚   β”‚   └── config.json
  β”‚   β”œβ”€β”€ temp
  β”‚   └── templates
  β”‚       β”œβ”€β”€ site/myst/book-theme
  β”‚       └── tex/myst/arxiv_two_column
  β”œβ”€β”€ images
  β”‚   β”œβ”€β”€ image.png
  β”‚   └── image.gif
  β”œβ”€β”€ 02-notebook.ipynb
  └── πŸ†• myst.yml

Running myst init added:

  • myst.yml - the configuration file for your myst project and site
  • _build - the folder containing the processed content and other site assets, which are used by the local web server.

The _build folder also contains your templates (including the site template you installed) and any exports you make (when we build a PDF the exported document will show up in the _build/exports folder). You can clean up the built files at any time using myst clean[2].

Configuration βš™οΈΒΆ

If we open and look inside our myst.yml we will see a basic configuration like this:

# See docs at:
version: 1
  # title:
  # description:
  keywords: []
  authors: []
  # github:
  # bibliography: []
  template: book-theme
  # title:
  # logo:
  nav: []
    - title: Learn More
  domains: []

There are two important parts to the myst.yml:

The project holds metadata about the collection of files, such as authors, affiliations and licenses for all of the files, any of these values can optionally be overridden in a file. To see all of the options see Frontmatter, which includes which fields can be overridden by files in the project.
The site holds template information about the website, such as the logo, navigation, site actions and which template to use.

πŸ›  In myst.yml: Change the "# title:" comment in site to "title: Fancy Title 🎩" and save

Saving the myst.yml will have triggered a "full site rebuild"[3] and in about ⚑️ 20ms ⚑️ take a look at the browser tab:

The site title will control site meta tags, and the browser-tab title, which is appended to each page title in the book-theme.

Figure 2:The site title will control site meta tags, and the browser-tab title, which is appended to each page title in the book-theme.

Separating Project and Site Configurations

You may separate the project and site configurations into multiple myst.yml files to configure your website. Each website needs a single site configuration at the root level; then any subdirectory with content may have its own project configuration with project-specific frontmatter. For example, given a content directory with all your markdown and notebooks,you can create a content/myst.yml file with project frontmatter:

version: 1
  title: ...
  authors: ...

and a root-level myst.yml file that references the project in the content subfolder:

version: 1
  template: book-theme
    - slug: my-content
      path: content

Doing this will keep the _build directory at the root level, but everything else outside of the content folder will be ignored. If you have a project in the same configuration file it can be accessed with path: .. Projects are "mounted" at the slug: (i.e. /my-content/) above.

More Coming Soonβ„’

Conclusion πŸ₯³ΒΆ

For now, that's it for this quickstart tutorial, we will add more about changing logos, themes, the table of contents, and much more soon! As for next steps you can export MyST Markdown as traditional documents like PDFs and Word, take a look at:

MyST Documents πŸ“‘

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

MyST Markdown Guide πŸ“–

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

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication