Skip To Article

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\LaTeX documents πŸ“‘
  • and create a website like this one 🌎

The current tutorial will help you get up and running from scratch.

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

Install the MyST Markdown CLIΒΆ

πŸ›  Install MyST using your preferred packaging ecosystem. (See Install the MyST Markdown Command Line Interface for more details).

conda-forge
PyPI
NPM

πŸ›  Install mamba (https://mamba.readthedocs.io), see Getting started with Miniforge and Python.

$ mamba --version
mamba 1.5.8
conda 24.7.1   

πŸ›  Install mystmd from conda-forge:

mamba install -c conda-forge mystmd

πŸ›  Then, check that MyST has successfully been installed:

$ myst -v
v1.3.4

Build your first MyST siteΒΆ

Next we’ll download some sample content and use MyST to render it as a local web server!

Download example contentΒΆ

We provide an example project that includes a few simple markdown files and some Jupyter Notebooks. Through the course of the tutorials we will add content to these documents that show off some of the features of MyST.

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

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

Initialize MyST in the content folder πŸš€ΒΆ

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: https://mystmd.org

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

Preview your MyST site locallyΒΆ

Preview a rendered version of the quickstart content to make sure that MyST is working properly.

πŸ›  When prompted, type Yes to install and serve your MyST content locally:

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

or manually serve the quickstart content with the following command:

myst start

Starting the server requires a theme, this will download the default book-theme from the MyST themes. This can take up to a minute the first time, and then will be cached in the _build/templates directory.

πŸ• Fetching template metadata from https://api.mystmd.org/templates/site/myst/book-theme
πŸ’Ύ 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 paper.md in 32 ms.
πŸ“– Built README.md 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[2]

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

The myst theme for the 01-paper.md page without any changes made.

FigureΒ 1:The myst theme for the 01-paper.md page without any changes made.

πŸŽ‰ Congratulations, you just build your first MyST site!

Configuration and structureΒΆ

The final section of this tutorial takes a closer look at the files that we just created, and aspects of your MyST project can be customized.

Folder StructureΒΆ

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

quickstart/
  β”œβ”€β”€ πŸ†• _build
  β”‚   β”œβ”€β”€ exports
  β”‚   β”œβ”€β”€ site
  β”‚   β”‚   β”œβ”€β”€ content
  β”‚   β”‚   β”œβ”€β”€ public
  β”‚   β”‚   └── config.json
  β”‚   β”œβ”€β”€ temp
  β”‚   └── templates
  β”‚       β”œβ”€β”€ site/myst/book-theme
  β”‚       └── tex/myst/arxiv_two_column
  β”œβ”€β”€ images
  β”‚   β”œβ”€β”€ image.png
  β”‚   └── image.gif
  β”œβ”€β”€ 01-paper.md
  β”œβ”€β”€ 02-notebook.ipynb
  β”œβ”€β”€ README.md
  └── πŸ†• 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[3].

Configure site and page optionsΒΆ

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

# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  # title:
  # description:
  keywords: []
  authors: []
  # github:
  # bibliography: []
site:
  template: book-theme
  # title:
  # options:
  #   logo: my_logo.png
  nav: []
  actions:
    - title: Learn More
      url: https://mystmd.org/guide
  domains: []

There are two important parts to the myst.yml:

project:
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.
site:
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”[4]. Take a look at the browser tab and you’ll see that it has updated:

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.


Next steps ➑️¢

That’s it for this quickstart tutorial! You’ve now got MyST installed locally, and the basic structure of a MyST project ready to improve. You are well on your way to getting started with myst.

Here are some things to try for next steps:

Check out the following tutorials for more step-by-step guides:

FootnotesΒΆ
  1. If you aren’t familiar with git, it isn’t required for this tutorial, you can download the zip file with the contents from the quickstart repository.

  2. If port 3000 is in use on your machine, an open port will be used instead, follow the link provided in the terminal.

  3. By default the myst clean command doesn’t remove installed templates or cached web responses; however, the function can with a:
    myst clean --all, or
    myst clean --templates --cache.

    Before deleting any folders myst will confirm what is going to happen, or you can bypass this confirmation with the -y option. For example:

    Deleting all the following paths:
    
      - _build/site
      - _build/templates
    
    ? Would you like to continue? Yes
    
    πŸ—‘ Deleting: _build/site
    πŸ—‘ Deleting: _build/templates
  4. If the server stopped, you can restart the server using myst start.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.