Writing in MyST Markdown

Supported file formats¶

After following Initialize your book, 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 Document 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 Document 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!

Markup

Result

intro.md

# 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!

$$x \times y = z$$

(1)

Sometimes when reading it is helpful to foster a tranquil environment. The image in Figure 1 would be a perfect spot!

The above tab-set shows both the contents of intro.md, and what the underlying MyST Document 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 Document Engine that powers Jupyter Book, see the MyST-MD authoring documentation.

Now that we have some content, we’re ready to build websites.