MyST Quick reference
Contents
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.
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:
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:
def square(x):
return x**2
Console#
```{code-block} console
---
caption: Interactive shell.
---
$ ls
a b c
```
becomes:
$ ls
a b c
Bash#
```{code-block} bash
---
caption: Bash code block.
---
# Comment
for i in "a b c"; do
print $i
done
```
becomes:
# 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
```
# 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
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:
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 10.
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. 209.
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
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:
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:
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 authorfirstauthor:secondauthor:year
for two authorsfirstauthor: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)