MySt and Markdown for Sphinx Cheatsheet#

I’ve never been a fan of Re-StructuredText, but most importantly I’m new to MySt, which leads to a lot of googling and painstaking trial-and-error while writing. Although my preferred references are the Jupyter Book MyST Cheatsheet, the Sphinx Book Theme Documentation, and the MyST Parser Reference, they are way too extensive, sometimes incorrect, and I don’t really use every directive or variant thereof. Therefore, I’ll use this post to gather the bits of the syntax and snippets I use the most.

Basics#

Your Extension and Parser#

Please double check which parser and extension you are using, the behaviors described here will differ depending on whether you’re using myst_nb, myst_parser, etc.

Markdown Notation#

Source

Result

*example*

example

**example**

example

_example_

example

~~example~~

example
Dwell on the beauty of life. Watch the stars, and see yourself running with them.

Marcus Aurelius

Comments#

% this is a comment

Emojis#

Emoji

Text

👍

thumbs-up

📌📍

pin

👨‍🔧

tradesperson

💡

idea, lightbulb

📚

books

📣

megaphone

📢

megaphone

🌎

world

🧭

compass

🧰🔧

tool, wrench

🔨

hammer

💻

computer, pc, laptop

🚀

rocket

🦊

fox

🔔

bell

⭐

star

👉👈👇👆

point

👋

wave

Font Awesome#

Source

Result

{fa}`check`

Images and Figures#

Scaled and Aligned Figure#

../../_images/linux.jpg

Here is my figure caption!#

There seems to be a bug whereby alignment of the content isn’t reset after the paragraph following a figure or the heading coming immediately after. That can be fixed with </br> as +++ and --- don’t help.

Figure with Caption and Label (name)#

../../_images/linux.jpg

caption#

HTML Image#

ubuntu

Image#

linux

Referencing Figures and Images#

Source

Result

{ref}`ubuntu`

link

{ref}`ubuntu` example

link example

{ref}`text <linux>`

text

Structure#

If needed, +++ can be used to break the paragraph.

Code#

Syntax Highlighting [4]#

```bash
$ echo 'Hello World!'
Hello World!

```

1$ echo 'Hello World!'
2Hello World!

```python
print('Hello World!')
```

1print('Hello World!')

Code-Cells and Output [5] [6]#

from datetime import datetime
text = f"Last executed on {datetime.now()}"
print(text)

Last executed on 2024-04-27 12:43:18.363001

Images and MyST-NB Metadata#

```{code-cell} ipython3
---
mystnb:
  image:
    width: 200px
    alt: fun-fish
    classes: shadow bg-primary
  figure:
    caption: |
      Hey everyone its **party** time!
    name: fun-fish
---
from IPython.display import Image
Image("sphinx-myst-markdown.md-data/ubuntu.png")
```

from IPython.display import Image
Image("sphinx-myst-markdown.md-data/ubuntu.png")
fun-fish

Hey everyone its party time!#

Math [7]#

Hello 👋, \(z=\sqrt{x^2+y^2}\) is an equation equivalent to $z=\sqrt{x^2+y^2}$ !

$$
z=\sqrt{x^3+y^3}
$$
\[ z=\sqrt{x^3+y^3} \]

```{math}
z=\sqrt{x^4+y^4}
```
\[z=\sqrt{x^4+y^4}\]

It’s also possible to use AMSMath syntax as follows:

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

\begin{align}
a_{11}& =b_{11}&
  a_{12}& =b_{12}\\
a_{21}& =b_{21}&
  a_{22}& =b_{22}+c_{22}
\end{align}

Admonitions#

example

example

Warning

example example

Tip

example example

Note

example example

Error

example example

Custom#

HTML Blocks and Custom Tags#

As documented here and here, it’s possible to use raw HTML and custom tags in MyST.

Source

Result

<tagname> text <tagname>

text

Hacky Image with Annotations#

While experimenting for 🎭 Best Fonts for Programming, I was looking for ways to easily annotate images and this occurred to me. It’s quite hacky, and I never did use it, but I might in the future and the idea seems solid (having numeric indicators and marginal comments).

```{div} custom-annotated-image

:::{figure} sphinx-myst-markdown.md-data/anonymous-pro.png
---
name: best-programming-fonts-anonymous-pro.png
align: left
---
This is my caption.
:::

`01` 

:::{margin}
Hello
:::

`02`

`03`

`04`

`05`

`06`

`07`

`08`

`09`

`10`

`11`

`12`

:::{margin}
World!
:::

`13` 

`14`

```
../../_images/anonymous-pro.png

This is my caption.#

01

02

03

04

05

06

07

08

09

10

11

12

13

14

ABlog [8]#

Warning

Note the quotes (") around the :format: and :date: arguments; they are necessary. Otherwise, ABlog will come into an error condition such as ERROR: Directive 'postlist': Invalid options YAML: while parsing a block mapping for :format: and ERROR: Directive 'postlist': Invalid options YAML: while scanning for the next token found character '%' that cannot start any token for :date:.

```{postlist} 1
:category: cheatsheets
:list-style: circle
:excerpts:
:sort:
:expand: Read more ...
:format: "{title} by {author} on {date}"
:date: "%A, %B %d, %Y"
:tags: git
:language: English
```

Result 👇

  • Git Revision Selection and Expressions A…B by Jayson Salazar Rodriguez on Saturday, July 15, 2023

    While using git it’s common to use object identifiers to operate on the underlying objects: checking branches out, reverting a commit, resetting to a given point in the history, and more.

    ../../_images/revision-parents-ancestors.png

    Read more ...

ReST#

I don’t personally like nor use ReST much, I feel it is way too verbose and convoluted with all those dots and colons. However, it’s useful to have a couple of syntax overviews handy. I mainly use the Tuto site on ReST and Sphinx, as well as the LPN Sphinx Primer and the Sublime and Sphinx Guide.

Kill (9-TERM) Processes with Expression(s) in Name or Call   Grieving the Early Internet 💾