These quickstart tutorials are to get you up and running on your local computer π©βπ»:
- learn how to write MyST Markdown π
- export PDF, Word and 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).
Not sure which to pick?
The easiest way to install MyST is with the mamba
package manager. mamba
is a cross-platform language-agnostic package manager that is useful for users across many data science languages like Python, R, Julia, and JavaScript.
π Install mamba
(https://
$ mamba --version
mamba 1.5.8
conda 24.7.1
π Install mystmd
from conda-forge
:
mamba install -c conda-forge mystmd
Install Node.js?
The mystmd
package on PyPI ships with the ability to install node
(https://nodejs.org). If you would prefer to install NodeJS manually, see Installing NodeJS:
π Install mystmd
:
pip install mystmd
π Ensure mystmd
is ready for use:
MyST needs node
(https://nodejs.org) in order to run correctly. If node
is not already installed, starting myst
will prompt you to install it:
$ myst -v
β Node.js (node) is required to run MyST, but could not be found`.
β Install Node.js in '/root/.local/share/myst/18.0.0'? (y/N): y
βοΈ Attempting to install Node.js in /root/.local/share/myst/18.0.0 ...
βΉοΈ Successfully installed Node.js 18.0.0
v1.3.4
π Install node
(https://nodejs.org), see Installing NodeJS
$ node -v
v20.4.0
π Then install mystmd
using npm, yarn or pnpm:
npm install -g 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.
π 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 othersite
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:
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
project:
title: ...
authors: ...
...
and a root-level myst.yml
file that references the project in the content
subfolder:
version: 1
site:
template: book-theme
projects:
- 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:
(e.g. /my-content/
above).
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:
Enhance your MyST documents with interactivity, open scholarship, and reproducibility.
Learn how to use computation and execution with Jupyter in MyST.
Export MyST documents to a Word document, PDF, and !
See an overview of MyST Markdown syntax with inline demos and examples.
Learn how to use MyST in Jupyter Interfaces.
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.
If port
3000
is in use on your machine, an open port will be used instead, follow the link provided in the terminal.By default the
myst clean
command doesnβt remove installed templates or cached web responses; however, the function can with a:myst clean --all
, ormyst 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
If the server stopped, you can restart the server using
myst start
.