MyST Quick reference#

Style guide#

Use Markedly Structured Text (MyST), not reStructured Text (rST).
Place each sentence on its own single line.

Headings#

Use # Heading 1 only at the top of each page.

Heading 2#

Heading 3#

Heading 4#

Refer to Heading 2.

Admonitions#

General admonition as warning

Text goes here.

Attention

This is an attention admonition.

Danger

This is a danger admonition.

Error

This is an error admonition.

Important

This is an important admonition.

Note

This is a note admonition.

Tip

This is a tip admonition.

Warning

This is a warning admonition.

Lists#

Itemized lists#

Level 1a
- Level 2a
  - Level 3a
  - Level 3b
- Level 2b
Level 1b
Level 1c

Definition lists#

Term 1: Definition of term 1
Term 2: Definition of term 2

Field lists#

field 1:: Description of field 1
field 2:: Description of field 2

Code blocks#

Listing 357 C++ code block.#

int
main(int argc, char* argv[]) {
    // Emphasized lines corresponding to body of main().
    return 0;
}

Listing 358 Python code block.#

def square(x):
    return x**2

Listing 359 Interactive shell.#

$ ls
a b c

Listing 360 Bash code block.#

# Comment
for i in "a b c"; do
  print $i
done

Listing 361 Config code block.#

# Comment
[pylithapp]
journal.device = color-console

[pylithapp.petsc]
ksp_rtol = 1.0e-3

Tables#

Please see Table 45. Table labels cannot contain more than one dash, so we use colons to separate the words in the label. This is likely a bug.

Table 45 Table caption#
Header 1	Header 2	Header 3
right aligned	centered	left aligned
more data, more data	yet more data	even more data

Figures#

Please see Fig. 212. Figure labels cannot contain more than one dash, so we use colons instead. This is likely a bug.

Screenshot — Fig. 212 This is the figure caption. Vector graphics should be provided in **both** PDF (latex output) and SVG (html output) formats. Raster graphics should be provided in either PNG or JPG formats (whichever is more compact).#

Math#

For unlabled equations you can use AMSTex environments, such as equation, gather and align. Unfortunately, Sphinx does not currently support labeled equations using AMSTex environments. Labeled equations must use the Markdown syntax as in equation (259).

Warning

A group of equations only has a single label, so if you need to label individual equations, place each one in its own math block.

Here is a single equation:

(256)#\[\begin{equation} F = m a \end{equation}\]

Here is a group of equations:

(257)#\[\begin{gather} f_1(x,y) = a_1 x + b_1 y + c_1 \\ f_2(x,y) = a_2 x + b_2 y + c_2 \end{gather}\]

Here is a group of aligned equations:

(258)#\[\begin{align} f_1(x,y) &= a_1 x + b_1 y + c_1 \\ f_2(x,y) &= a_{xx} x^2 + a_{xy} x y + a_{yy} y^2 + a_x x + a_y y + a_0 \end{align}\]

Here is a labeled equation (equation (259)):

(259)#\[F = m a\]

Citations#

Traditional citation [Aagaard et al., 2007]. Citation as noun Bathe [1995].

Table of contents#

# Table of contents tree with a maximum depth of 1
:::{toctree}
---
maxdepth: 1
---
one.md
two.md
:::

# Table of contents tree with no maximum depth specified.
:::{toctree}
one.md
two.md
:::