Ctrl+K

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.

See also

This is a seealso admonition.

TODO

This is a custom TODO admonition.


Becomes:

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

## Lists

### Itemized lists

```md
* 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 3 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 4 Python code block.#
def square(x):
    return x**2

Console#

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

becomes:

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

[pylithapp.petsc]
ksp_rtol = 1.0e-3

Captions are optional.

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 1 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 1.

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/logos/logo_avni_color_withname.svg" alt="Screenshot"  width="100%"/>

This is the figure caption.
```

to get this:

Screenshot

Fig. 1 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. 1.

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/logos/logo_avni_color_withname.png
:alt: AVNI Logo
:width: 80%
:align: center
```

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

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

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

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

(3)#\[\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}`Moulik:2014cr`.
Citation as noun {cite:t}`Moulik:2014cr`.
Use a comma for multiple, like {cite:t}`Moulik:2014cr,MoulikEtAl2021`.

becomes

Traditional citation [ME14]. Citation as noun Moulik and Ekström [ME14]. Use a comma for multiple, like Moulik and Ekström [ME14], Moulik et al. [MLR+21].

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)

On this page
Edit this page
Show Source