This was created from:
```md
Term *with Markdown*
: Definition [with reference](syntax/definition-lists)
A second paragraph
Term 2
~ Definition 2a
~ Definition 2b
Term 3
: A code block
: > A quote
: A final definition, that can even include images:
```
(syntax/images)=
## Images
MyST provides a few different syntaxes for including images in your documentation, as explained below.
The first is the standard Markdown syntax:
```md
```
This will correctly copy the image to the build folder and will render it in all output formats (HTML, TeX, etc).
However, it is limited in the configuration that can be applied, for example setting a width.
As discussed [above](syntax/directives), MyST allow for directives to be used such as `image` and `figure` (see {ref}`the sphinx documentation
```
Allowed attributes are equivalent to the `image` directive: src, alt, class, width, height and name.
Any other attributes will be dropped.
HTML image can also be used inline!
I'm an inline image:
(syntax/figures)=
## Markdown Figures
By adding `"colon_fence"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
we can combine the above two extended syntaxes,
to create a fully Markdown compliant version of the `figure` directive named `figure-md`.
:::{important}
`myst_figure_enable` with the `figure` directive is deprecated and replaced by `myst_enable_extensions = ["colon_fence"]` and `figure-md`.
:::
The figure block must contain **only** two components; an image, in either Markdown or HTML syntax, and a single paragraph for the caption.
The title is optional and taken as the reference target of the figure:
```md
:::{figure-md} fig-target
:class: myclass
This is a caption in **Markdown**
:::
```
:::{figure-md} fig-target
:class: myclass
This is a caption in **Markdown**
:::
As we see here, the target we set can be referenced:
```md
[Go to the fish!](fig-target)
```
[Go to the fish!](fig-target)
(syntax/html-admonition)=
## HTML Admonitions
By adding `"html_admonition"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
you can enable parsing of `` HTML blocks.
These blocks will be converted internally to Sphinx admonition directives, and so will work correctly for all output formats.
This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
If the first element within the `div` is `
` or `
```
During the Sphinx render, both the `class` and `name` attributes will be used by Sphinx, but any other attributes like `style` will be discarded.
:::{warning}
There can be no empty lines in the block, otherwise they will be read as two separate blocks.
If you want to use multiple paragraphs then they can be enclosed in `
```
:::
You can also nest HTML admonitions:
```html
```
(syntax/amsmath)=
## Direct LaTeX Math
By adding `"amsmath"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
you can enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations.
These top-level math environments will then be directly parsed:
> equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.
As expected, environments ending in `*` will not be numbered, for example:
```latex
\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}
\begin{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\end{align}
```
\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}
\begin{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\end{align}
:::{note}
`\labels` inside the environment are not currently identified, and so cannot be referenced.
We hope to implement this in a future update (see [executablebooks/MyST-Parser#202](https://github.com/executablebooks/MyST-Parser/issues/202))!
:::
:::{important}
See also [how Mathjax is configured with MyST-Parser](syntax/mathjax).
:::
This syntax will also work when nested in other block elements, like lists or quotes:
```md
- A list
- \begin{gather*}
a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
\end{gather*}
> A block quote
> \begin{gather*}
a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
\end{gather*}
```
- A list
- \begin{gather*}
a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
\end{gather*}
> A block quote
> \begin{gather*}
a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
\end{gather*}
`, then this will be set as the admonition title. All internal text (and the title) will be parsed as MyST-Markdown and all classes and an optional name will be passed to the admonition: ```html
This is the **title**
This is the *content*This is the **title**
This is the *content*
`: ```html
Paragraph 1
Paragraph 2
Paragraph 1
Paragraph 2
Some **content**
A *title*
Paragraph 1
Paragraph 2
Some **content**
A *title*
Paragraph 1
Paragraph 2