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.

Also: numref will not work in this file since its not part of the main filetree. But it will work in anything thats a part of a toctree.

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:

Heading 1#

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.

See also

This is a seealso admonition.

TODO

This is a custom TODO 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:

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:

Python code block.#
def square(x):
    return x**2

Console#

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

becomes:

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:

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
```
Config code block.#
# Comment
[pylithapp]
journal.info.problem = 1

[pylithapp.petsc]
ksp_rtol = 1.0e-3

Captions are optional.

Codeblocks from external files#

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

becomes:

subsection Material model
  set Model name = ascii reference profile

  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

  set Material averaging = harmonic average
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 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 tab:quickref.

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

Note

The numref command doesn’t work in this particular file because its not a part of the main file structure. It does work in the manual, as long as the file is in a toctree.

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:

Screenshot

This is the figure caption.#

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:quickref.

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 seperated with colons.

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

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

()#\[F = m a\]
Refer to the labeled equation like {math:numref}`eqn:one:two`.

Refer to the labeled equation like (). (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:

()#\[\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:

()#\[\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}\]

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 footnote1 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)

1

And here’s what the footnote says (put this at the very bottom of the document)