MyST Quick reference#

Note

Everything in this file will look like garbage in a regular markdown viewer, like if you’re viewing this on github. Viewing it on readthedocs will render everything properly.

Text#

Put single asterisks around text you *want to italicize*, but double asterisks around text you **want to bold**.

Put single asterisks around text you want to italicize, but double asterisks around text you want to bold.

Headings#

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

becomes (note that the first heading is not rendered to avoid a duplicate heading in the table of contents):

Heading 2#

Heading 3#

Heading 4#

All standalone .md files must start with a level 1 header, regardless of whether it is a chapter, section, or subsection. Subheaders within the same file can start with ## and so on.

For a section to be referenced, it must have a header tag like so:

(sec:myst-quickref)=
# MyST Quick reference

To refer to the section:

Include a section reference to {ref}`sec:myst-quickref` in a sentence like so.

Include a section reference to MyST Quick reference in a sentence like so.

Admonitions#

:::{admonition} General admonition as warning
:class: 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.
:::

:::{seealso}
This is a `seealso` admonition.
:::

:::{admonition} TODO
:class: error

This is a custom `TODO` admonition.
:::

Becomes:

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 1
  * Level 2
    * Level 3

Level 1
- Level 2
  - Level 3

Definition lists#

Term 1
: Definition of term 1

Term 2
: Definition of term 2

becomes:

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

Code blocks#

C++#

```{code-block} c++
---
caption: C++ code block.
emphasize-lines: 3-4
---
int
main(int argc, char* argv[]) {
    // Emphasized lines corresponding to body of main().
    return 0;
}
```

becomes:

Listing 1 C++ code block.#

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

python#

```{code-block} python
---
caption: Python code block.
---
def square(x):
    return x**2
```

becomes:

Listing 2 Python code block.#

def square(x):
    return x**2

Console#

```{code-block} console
---
caption: Interactive shell.
---
$ ls
a b c
```

becomes:

Listing 3 Interactive shell.#

$ ls
a b c

Bash#

```{code-block} bash
---
caption: Bash code block.
---
# Comment
for i in "a b c"; do
  print $i
done
```

becomes:

Listing 4 Bash code block.#

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

cfg#

```{code-block} cfg
---
caption: Config code block.
---
# Comment
[pylithapp]
journal.info.problem = 1

[pylithapp.petsc]
ksp_rtol = 1.0e-3
```

Listing 5 Config code block.#

# Comment
[pylithapp]
journal.info.problem = 1

[pylithapp.petsc]
ksp_rtol = 1.0e-3

Captions are optional.

Codeblocks from external files#

```{literalinclude} /user/cookbooks/cookbooks/burnman/doc/material_model.part.prm
```

becomes:

subsection Material model
  set Model name = ascii reference profile
  set Material averaging = harmonic average

  subsection Ascii data model
    set Data file name = isentrope_properties.txt
    set Data directory = $ASPECT_SOURCE_DIR/data/adiabatic-conditions/ascii-data/
  end

  subsection Ascii reference profile
    set Thermal viscosity exponent = 10.0
    set Viscosity prefactors = 1.0, 0.1, 1.0, 10.0
  end
end

When working in cookbooks, prm files should generally be in the same folder as the .md file referencing them, so the filepath will probably look more like this:

```{literalinclude} material_model.part.prm
```

Tables#

```{table} Table caption
:name: tab:quickref
|             Header 1 |   Header 2    | Header 3       |
| -------------------: | :-----------: | :------------- |
|        right aligned |   centered    | left aligned   |
| more data, more data | yet more data | even more data |
```

becomes:

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

Refer to it with the numref tag, like so:

Please see {numref}`tab:quickref`.

Please see Table 12.

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

Figures#

Format a figure like this:

```{figure-md} fig:quickref
<img src="_static/images/aspect_logo.*" alt="Screenshot"  width="100%"/>

This is the figure caption.
```

to get this:

Put the filename and relative path in “img src”, but leave the file extension as .* instead of .png or whatever. Allowable formats for figures include SVGs, PNGs, and JPGs, but not PDFs unfortunately.

Refer to it like:

Please see {numref}`fig:quickref`.

Please see Fig. 241.

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

Sphinx does not support the use of subfigures. Combine any sub-figures you want to include into one file. We recommend inkscape for this purpose.

Figures need to have a caption or they will not be rendered. If you want to include figures without captions you can instead do:

```{image} _static/images/aspect_logo.png
:alt: ASPECT Logo
:width: 80%
:align: center
```

Math#

Parameter file referencing#

Parameter files can be referenced like a link. You can leave the link name out to get the heading information, or choose your own. This should look like the LaTeX referencing. Spaces in parameter and subsection names should be replaced by “_20”. Subsections should be separated with colons.

[](parameters:CFL_20number)
See all [particle interpolator parameters](parameters:Postprocess/Particles/Interpolator)

Parameter name: CFL number See all particle interpolator parameters

Math#

Inline math works just like in latex. Use dollar signs to put stuff like $\eta_r(z)$ in a sentence. That’s:

Use dollar signs to put stuff like $\eta_r(z)$ in a sentence.

Be aware that not all latex packages are known by Sphinx, so some commands will need to be reformatted (i.e., \num{4e5} needs to be rewritten as 4\times 10^{5}.)

For math blocks:

```{math}
:label: eqn:one:two
F = m a
```

becomes

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

Refer to the labeled equation like {math:numref}`eqn:one:two`.

Refer to the labeled equation like (57). (The label is not necessary if the equation doesn’t have one, in which case it would be formatted like):

```{math}
F = ma
```

The split environment is built into the math directive; which allows you to use one align operator (&).

```{math}
:label: eq:aligned
  -\nabla \cdot \left[2\eta
   \left(\varepsilon(\mathbf u) - \frac{1}{3}(\nabla \cdot \mathbf u)\mathbf 1\right)\right]
   + \nabla p' &=  -\bar \alpha \bar\rho T' \mathbf g \qquad \textrm{in $\Omega$},  \\
  \nabla \cdot (\bar\rho \mathbf u) &= 0  \qquad  \textrm{in $\Omega$}.
```

becomes:

(58)#\[\begin{split} -\nabla \cdot \left[2\eta \left(\varepsilon(\mathbf u) - \frac{1}{3}(\nabla \cdot \mathbf u)\mathbf 1\right)\right] + \nabla p' &= -\bar \alpha \bar\rho T' \mathbf g \qquad \textrm{in $\Omega$}, \\ \nabla \cdot (\bar\rho \mathbf u) &= 0 \qquad \textrm{in $\Omega$}.\end{split}\]

If you require more than one alignment character you need to start and end an additional aligned environment. Be sure to add the same number of align operators (&) to each line and use \\ to denote a new line.

```{math}
:label: eq:aligned
\begin{aligned}
  -\nabla \cdot \left[2\eta
   \left(\varepsilon(\mathbf u) - \frac{1}{3}(\nabla \cdot \mathbf u)\mathbf 1\right)\right]
   + \nabla p' &=  -\bar \alpha \bar\rho T' \mathbf g & \qquad  & \textrm{in $\Omega$},  \\
  \nabla \cdot (\bar\rho \mathbf u) &= 0  & \qquad  & \textrm{in $\Omega$}.
\end{aligned}
```

becomes:

(59)#\[\begin{split}\begin{aligned} -\nabla \cdot \left[2\eta \left(\varepsilon(\mathbf u) - \frac{1}{3}(\nabla \cdot \mathbf u)\mathbf 1\right)\right] + \nabla p' &= -\bar \alpha \bar\rho T' \mathbf g & \qquad & \textrm{in $\Omega$}, \\ \nabla \cdot (\bar\rho \mathbf u) &= 0 & \qquad & \textrm{in $\Omega$}. \end{aligned}\end{split}\]

Links#

[Put a link in text](https://en.wikipedia.org/wiki/Gibbs_free_energy) or just post the full link:
<https://en.wikipedia.org/wiki/Gibbs_free_energy>

becomes:

Put a link in text or just post the full link: https://en.wikipedia.org/wiki/Gibbs_free_energy

Citations#

Traditional citation {cite}`kronbichler:etal:2012`.
Citation as noun {cite:t}`kronbichler:etal:2012`.
Use a comma for multiple, like {cite:t}`kronbichler:etal:2012,heister:etal:2017`.

becomes

Traditional citation [Kronbichler et al., 2012]. Citation as noun Kronbichler et al. [2012]. Use a comma for multiple, like Dannberg and Heister [2016], Kronbichler et al. [2012].

If the paper you wish to cite is not already in references.bib, you will need to add its bibtex entry. Please format the citation tag as:

firstauthor:year for one author
firstauthor:secondauthor:year for two authors
firstauthor:etal:year for more than two authors

where firstauthor and secondauthor refer to the last names of the authors.

Footnotes#

Here's how you put a footnote[^footnote1] in a sentence.

Here’s how you put a footnote[1] in a sentence (see the bottom of this file).

See here for more#

https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html or https://jupyterbook.org/en/stable/reference/cheatsheet.html

footnote (again)#

[^footnote1]: And here's what the footnote says (put this at the very bottom of the document)

MyST Quick reference

Contents

MyST Quick reference#

Text#

Headings#

Heading 2#

Heading 3#

Heading 4#

Admonitions#

Lists#

Itemized lists#

Definition lists#

Code blocks#

C++#

python#

Console#

Bash#

cfg#

Codeblocks from external files#

Tables#

Figures#

Math#

Parameter file referencing#

Math#

Links#

Citations#

Footnotes#

See here for more#

footnote (again)#