Markup

The most common and simple formatting actions are supported natively in both rST and MyST, and if you are reading this, chances are you already know which syntax to use for things like titles, bullet lists or bold text.

More complex formatting (or special functionality!) can also be achieved with roles and directives, two key concepts in sphinx that are covered in the following pages. The resources below generally combine markup, roles and directives (without distinguishing if their goal is formatting or not).

There is one very important aspect that is often overlooked, but that is key to both rST and MyST, which is that both support indefinite nesting of markup and directives. See for yourselves:

Rendered content

1. We start with a numbered list

   Within the list we quote a section of some documentation

   Important

   The documentation has an info box with some code inside it:

   print("Nested formatting yay!")
   

2. We continue the list and markdown knows that it’s the same list and not a new one.

Raw content

1. We start with a numbered list

   > Within the list we quote a section of some documentation
   >
   > :::{important}
   > The documentation has an info box with some code inside it:
   >
   > ```
   > print("Nested formatting yay!")
   > ```
   > :::

1. We continue the list and markdown knows that it's the same list and not a new one.

rST	MyST
rST documentation in Sphinx docs	MyST-Parser docs
rST documentation in Docutils docs	MyST-NB docs
rST cheatsheet by Thomas Cokelaer	MyST cheatsheet in jupyterbook docs