Writing in MyST Markdown
Use MyST Markdown to author rich narrative and integrate computation.
Supported file formats¶
After following Initialise a project, our book has a myst.yml that contains some metadata including a title, description, and an author list. Let’s now add some content! The MyST engine that powers Jupyter Book supports a few different file formats for authoring content:
- MyST Markdown
.md - Jupyter Notebook
.ipynb - LaTeX
.tex
In this tutorial, we’ll author a simple page intro.md using MyST Markdown, a markup format based upon the CommonMark Markdown implementation.
Writing with MyST Markdown¶
MyST is designed for creating publication-quality, computational documents. By building on top of CommonMark Markdown, MyST markup is designed to be readable and compatible with a large number of existing editors.[1] As a CommonMark superset, the following markup is all valid MyST:
The most notable way that MyST extends CommonMark is through the introduction of roles and directives. Roles are a mechanism add semantic to inline markup, e.g. the delete role:
Directives serve a similar function for block level markup, like images:
Directives may have a body, like the caption:
1 2 3:::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true I'm a nice sunset! :::
And/or an argument, like the image URL:
1 2 3:::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true I'm a nice sunset! :::
They can even take options:
1 2 3 4 5:::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true :align: center I'm a nice sunset! :::
The MyST-MD engine defines a large number of pre-existing roles and directives, such as the figure directive, which are defined in the MyST guide (see Roles and Directives). The MyST guide defines a helpful overview of MyST Markdown syntax in MyST Syntax Overview
Having explored the supported syntax for writing MyST, let’s create a simple intro.md file that showcases these features!
# Introduction
I am a book about ... something! Wikipedia has [information about books](wiki:book): hover over the link for more information.
% An admonition containing a note
:::{note}
Books are usually written on paper ... But Jupyter Book can create _websites_!
:::
If you sold 100 books at \$10 per book, you'd have \$1000 dollars according to [](#eq:book). If instead you publish your Jupyter Book to the web for free, you'd have \$0 dollars!
% An arbitrary math equation
:::{math}
:name: eq:book
x \times y = z
:::
Sometimes when reading it is helpful to foster a _tranquil_ environment. The image in [](#fig:mountains) would be a perfect spot!
% A figure of a photograph of some mountains, followed by a caption
:::{figure} https://github.com/rowanc1/pics/blob/main/mountains.png?raw=true
:label: fig:mountains
A photograph of some beautiful mountains to look at whilst reading.
:::Introduction¶
I am a book about ... something! Wikipedia has information about books: hover over the link for more information.
If you sold 100 books at $10 per book, you’d have $1000 dollars according to (1). If instead you publish your Jupyter Book to the web for free, you’d have $0 dollars!
Sometimes when reading it is helpful to foster a tranquil environment. The image in Figure 1 would be a perfect spot!
Figure 1:A photograph of some beautiful mountains to look at whilst reading.
The above tab-set shows both the contents of intro.md, and what the underlying MyST-MD engine produces when you build the project as a website. To learn more about the supported syntax of MyST Markdown, and the features supported by the MyST-MD engine that powers Jupyter Book, see the MyST-MD authoring documentation.
Now that we have some content, we’re ready to Build a website.
Whilst specialised MyST integrations provide the best editing experience, most editors that understand Markdown will be able to make some sense of a MyST document.