Example syntax for myst

As a base, Myst adheres to the CommonMark specification.
For this, it uses the Mistletoe project,
which is a well-structured markdown parser for Python that is CommonMark-compliant
and also extensible.

Myst adds several new syntax options that extend its functionality to be used
with Sphinx, the documentation generation engine used extensively in the Python
ecosystem. Sphinx uses reStructuredText by default, which is both more
powerful than Markdown, and also (arguably) more complex to use.

This project is an attempt to have the best of both worlds: the flexibility
and extensibility of Sphinx with the simplicity and readability of Markdown.

Here are a few major extensions from the CommonMark flavor of markdown

Directives - a block-level extension point

Directives syntax is defined with triple-backticks and curly-brackets. It
is effectively a code block with curly brackets around the language, and
a directive name in place of a language name. It is similar to how RMarkdown
defines “runnable cells”. Here is the basic structure

```{directivename} Directive arguments
---
optional: yaml
keyval: parameterization
---
My directive content.
```

For example, the following code:

```{admonition} This is my admonition
This is my note
```

Will generate this admonition:

This is my admonition

This is my note

For directives that are meant to parse content for your site, you may use
markdown as the markup language inside…

```{admonition} My markdown link
Here is [markdown link syntax](https://jupyter.org)
```

Parameterizing directives

For directives that take parameters as input, you may parameterize them by
beginning your directive content with YAML frontmatter. This needs to be
surrounded by --- lines. Everything in between will be parsed by YAML and
passed as keyword arguments to your directive. For example:

```{code-block} python
---
lineno-start: 10
emphasize-lines: 1, 3
caption: |
    This is my
    multi-line caption. It is *pretty nifty* ;-)
---
a = 2
print('my 1st line')
print(f'my {a}nd line')
```
This is my
multi-line caption. It is pretty nifty ;-)
10
11
12
13

a = 2
print('my 1st line')
print(f'my {a}nd line')

Nesting directives

You can nest directives by ensuring that the ticklines corresponding to the
outermost directive are longer than the ticklines for the inner directives.
For example, nest a warning inside a note block like so:

````{note}
The next info should be nested
```{warning}
Here's my warning
```
````

Here’s how it looks rendered:

Note

The next info should be nested

Warning

Here’s my warning

This can really be abused if you’d like ;-)

Note

The next info should be nested

Warning

Here’s my warning

Yep another admonition

# All this fuss was about this boring python?!
print('yep!')

Roles - an in-line extension point

Roles are similar to directives - they allow you to define arbitrary new
functionality in Sphinx, but they are use in-line. To define an in-line
role, use the following form:

{role-name}`role content`

For example, the following code:

Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`

Becomes:

Since Pythagoras, we know that \(a^2 + b^2 = c^2\)

You can use roles to do things like reference equations and other items in
your book. For example:

```{math} e^{i\pi} + 1 = 0
---
label: euler
---
```

Euler's identity, equation {math:numref}`euler`, was elected one of the
most beautiful mathematical formulas.

Becomes:

(1)\[e^{i\pi} + 1 = 0\]

Euler’s identity, equation {DOESN’T WORKeq}euler, was elected one of the
most beautiful mathematical formulas.