### Setup Pre-commit Hooks

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/contributing.md

Install and configure pre-commit hooks to automatically format code and check for linting errors before committing.

```shell
>> cd MyST-Parser
>> pre-commit install
```

--------------------------------

### Install sphinx-design

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Install the sphinx-design package using pip. This extension allows for the creation of responsive web components.

```shell
pip install sphinx-design
```

--------------------------------

### Role Content Parsing Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

Illustrates how role content can be parsed differently based on the role, using the `ref` role as an example.

```markdown
`Content to display <myref>`
```

--------------------------------

### Install MyST Parser with Pip

Source: https://github.com/executablebooks/myst-parser/blob/master/README.md

Install the MyST parser using pip. This is an alternative installation method.

```bash
pip install myst-parser
```

--------------------------------

### Inline Math Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates inline math rendering using \( ... \).

```text
\(a=1\)
```

--------------------------------

### Install sphinxcontrib-mermaid

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Install the sphinxcontrib-mermaid package using pip. This extension enables the rendering of Mermaid diagrams.

```shell
pip install sphinxcontrib-mermaid
```

--------------------------------

### MyST FrontMatter Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

A YAML block at the start of the document enclosed by `---`.

```yaml
---
key: value
---
```

--------------------------------

### Python Directive Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_syntax_elements.md

Demonstrates the use of a Python directive with an argument.

```python
a = 1
```

--------------------------------

### Paragraph Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

General inline text.

```markdown
any *text*
```

--------------------------------

### Default Substitution Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/substitutions/index.md

Shows a basic substitution that is processed by default.

```markdown
output with *Markdown* nested substitution
```

--------------------------------

### Install MyST Parser with Conda

Source: https://github.com/executablebooks/myst-parser/blob/master/README.md

Install the MyST parser using Conda. This is the recommended method for managing environments.

```bash
conda install -c conda-forge myst-parser
```

--------------------------------

### Display Math Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates display math rendering using \\\\[ ... \\\\] for simple equations.

```text
\\\\[x=5\\\\]
```

--------------------------------

### Example with Admonition and Parameter Options

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Shows how to use admonition directives with custom classes and content within colon fences.

```markdown
:::::{myst-example}

:::{admonition} This *is* also **Markdown**
:class: warning

This text is **standard** _Markdown_
:::

:::::
```

--------------------------------

### Footnote Definition and Reference Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Provides an example of manually and auto-numbered footnote references and their definitions.

```myst
- This is a manually-numbered footnote reference.[^3]
- This is an auto-numbered footnote reference.[^myref]

[^myref]: This is an auto-numbered footnote definition.
[^3]: This is a manually-numbered footnote definition.
```

--------------------------------

### Install MyST Parser for Package Development

Source: https://github.com/executablebooks/myst-parser/blob/master/README.md

Install MyST parser in editable mode for development, including extra dependencies for code style, linking, testing, and Read the Docs compatibility.

```bash
git clone https://github.com/executablebooks/MyST-Parser
cd MyST-Parser
git checkout master
pip install -e .[code_style,linkify,testing,rtd]
```

--------------------------------

### Docutils CLI Help and Basic Usage

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/docutils.md

Demonstrates how to get help for a Docutils CLI command and how to pipe input or provide a file path for conversion.

```console
$ myst-docutils-html --help
$ echo "Hello World" | myst-docutils-html
$ myst-docutils-html hello-world.md
```

--------------------------------

### Definition List Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Demonstrates the basic syntax for creating definition lists in MyST Markdown.

```myst
Term 1
: Definition

Term 2
: Longer definition

  With multiple paragraphs

  - And bullet points
```

--------------------------------

### List Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Bullet points or enumerated lists, including nested items.

```markdown
- item
  - nested item
1. numbered item
```

--------------------------------

### Example Wiki Link

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Demonstrates a link using the 'wiki' scheme, which is converted to a Wikipedia URL based on the custom configuration.

```markdown
[URI](wiki:Uniform_Resource_Identifier#URI_references)
```

--------------------------------

### Inline Code Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/basic/content.md

Shows how inline code with special characters is rendered.

```text
` a=1{`} `
```

--------------------------------

### Strong Emphasis Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Renders text as bold.

```md
**strong**
```

--------------------------------

### Heading Starts at H1

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/reporter_warnings.md

This warning advises against starting document headings at H1. It's recommended to start with H2 to allow for a main document title.

```markdown
## title 1
```

--------------------------------

### Field List Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Illustrates the syntax for creating field lists, commonly used in source code documentation.

```myst
:param arg1: A description of arg1
:param arg2: A longer description,
    with multiple lines.

    - And bullet points
:return: A description of the return value
```

--------------------------------

### Setext Heading Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Underlined header using multiple `=` or `-` characters.

```markdown
Header
======
```

--------------------------------

### Use the mermaid directive

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Example of using the 'mermaid' directive within a MyST Markdown file to embed a Mermaid diagram. Ensure the extension is installed and configured.

```markdown
:::{myst-example}
Here's a cool mermaid diagram!

```{{mermaid}}
sequenceDiagram
  participant Alice
  participant Bob
  Alice->John: Hello John, how are you?
  loop Healthcheck
      John->John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail...
  John-->Alice: Great!
  John->Bob: How about you?
  Bob-->John: Jolly good!
```
:::
```

--------------------------------

### HTML Block Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Any valid HTML block, rendered in HTML output only.

```html
<p>some text</p>
```

--------------------------------

### Python Substitution Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/substitutions/index.md

Illustrates a substitution that is not processed, likely due to context or configuration.

```python
{{ text_with_nest }}
```

--------------------------------

### Emphasis Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Renders text in italics.

```md
*emphasis*
```

--------------------------------

### Bullet List Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_syntax_elements.md

A bullet list with two items, demonstrating different bullet characters.

```markdown
- *foo*
* bar
```

--------------------------------

### Docutils Configuration File Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/docutils.md

Shows how to configure MyST-Parser's behavior for general processing and specific HTML output using a docutils.conf file.

```ini
# These entries affect all processing:
[general]
myst-enable-extensions: deflist,linkify
myst-footnote-transition: no
myst-substitutions:
    key1: value1
    key2: value2

# These entries affect specific HTML output:
[html writers]
embed-stylesheet: no

[html5 writer]
stylesheet-dirs: path/to/html5_polyglot/
stylesheet-path: minimal.css, responsive.css
```

--------------------------------

### MyST Target Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Precedes an element to target, such as a header.

```markdown
(target)=
```

--------------------------------

### Pytest Sphinx Integration Test Example

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

An example of a pytest test function for Sphinx integration, utilizing the `@pytest.mark.sphinx` decorator and common fixtures like `app`, `status`, `warning`, and `get_sphinx_app_output`.

```python
import pytest

@pytest.mark.sphinx(
    buildername="html",
    srcdir="path/to/sourcedir",
)
def test_example(app, status, warning, get_sphinx_app_output):
    app.build()
    assert "build succeeded" in status.getvalue()
    warnings = warning.getvalue().strip()
    assert warnings == ""
```

--------------------------------

### MyST Role Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Represents a role in MyST Markdown.

```markdown
{rolename}`interpreted text`
```

--------------------------------

### Basic Admonition Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Demonstrates the basic usage of a 'tip' admonition. Ensure the 'colon_fence' extension is enabled for MyST Markdown content within admonitions.

```markdown
:::
:::{tip}
Let's give readers a helpful hint!
:::
:::
```

--------------------------------

### Numbered Code Block Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/extended_syntaxes/index.md

Demonstrates a numbered code block in TypeScript.

```typescript
type Result = "pass" | "fail"

```

--------------------------------

### AutoLink Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Creates a link that is displayed in the final output. Supports URL formats.

```md
<http://www.google.com>
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Illustrates the recommended format for commit messages, including an emoji, keyword, concise summary, and optional detailed explanation.

```text
<EMOJI> <KEYWORD>: Summarize in 72 chars or less (#<PR>)

Optional detailed explanation.
```

--------------------------------

### Admonition Directive Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

A simple example of using the 'admonition' directive in MyST. This is useful for creating distinct blocks of information like notes or warnings.

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

--------------------------------

### Python Function Definition

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/basic/content.md

A basic Python function definition example.

```python
def func(a, b=1):
    print(a)

```

--------------------------------

### Python Docstring Example with Type Annotations

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Demonstrates the use of Sphinx-style docstrings with complete type annotations for function signatures, including parameters, return types, and raised exceptions.

```python
def parse_directive_text(
    directive_class: type[Directive],
    first_line: str,
    content: str,
    *, 
    validate_options: bool = True,
) -> tuple[list[str], dict[str, Any], list[str], int]:
    """Parse directive text into its components.

    :param directive_class: The directive class to parse for.
    :param first_line: The first line (arguments).
    :param content: The directive content.
    :param validate_options: Whether to validate options against the directive spec.
    :return: Tuple of (arguments, options, body_lines, body_offset).
    :raises MarkupError: If the directive text is malformed.
    """
    ...
```

--------------------------------

### Quote Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Quoted text block.

```markdown
> this is a quote
```

--------------------------------

### Example Data Regression Tests

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/test_infrastructure.md

Demonstrates how to use pytest-regressions for checking dictionary and string outputs. The first run will fail and generate expected output files.

```python
def test_example_dict(data_regression):
    data_regression.check({
        "key1": "value1",
        "key2": "value2",
        "more": "data...",
    })
def test_example_str(file_regression):
    file_regression.check("a very long string...")
```

--------------------------------

### Example DOI Link

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Shows a link using the 'doi' scheme, converted to a DOI URL using the configured template.

```markdown
<doi:10.1186/gm483>
```

--------------------------------

### Basic CSV Table Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/tables.md

This snippet demonstrates the basic usage of the `csv-table` directive with a header and data. It shows how to define column headers and provide rows of data.

```myst
```{csv-table} Frozen Delights!
:header: >
:    "Treat", "Quantity", "Description"
:widths: 15, 10, 30

"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
```
```

--------------------------------

### Ordered List Styling (Upper Alpha)

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/attributes.md

Example of an ordered list using upper-alpha styling.

```markdown
1. a
2. b
. {style=upper-alpha}
```

--------------------------------

### Comment Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Demonstrates how to add comments to MyST Markdown documents using the '%' character.

```myst
% my comment
```

--------------------------------

### MyST Inline Math Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Inline math content enclosed by `$` or `\(`...`\)`.

```latex
$a=1$ or $$a=1$$
```

--------------------------------

### MyST Cross-reference Examples

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Demonstrates various MyST-native and Sphinx role syntaxes for creating cross-references, including autolinks and explicit text links.

```myst
:::
  :header-rows: 1

  * - Type
    - Syntax
    - Rendered

  * - Autolink, full
    - `<inv:sphinx:std:doc#index>`{l=myst}
    - <inv:sphinx:std:doc#index>

  * - Link, full
    - `[Sphinx](inv:sphinx:std:doc#index)`{l=myst}
    - [Sphinx](inv:sphinx:std:doc#index)

  * - Autolink, no type
    - `<inv:sphinx:std#index>`{l=myst}
    - <inv:sphinx:std#index>

  * - Autolink, no domain
    - `<inv:sphinx:*:doc#index>`{l=myst}
    - <inv:sphinx:*:doc#index>

  * - Autolink, only name
    - `<inv:#*.Sphinx>`{l=myst}
    - <inv:#*.Sphinx>
:::
```

```myst
Sphinx roles:

- {ref}`syntax/referencing`, {ref}`Explicit text <syntax/referencing>`
- {term}`my other term`
- {doc}`../intro`, {doc}`Explicit text <../intro>`
- {download}`example.txt`, {download}`Explicit text <example.txt>`
- {py:class}`mypackage.MyClass`, {py:class}`Explicit text <mypackage.MyClass>`
- {external:class}`sphinx.application.Sphinx`, {external:class}`Explicit text <sphinx.application.Sphinx>`
- {external+sphinx:ref}`code-examples`, {external+sphinx:ref}`Explicit text <code-examples>`

MyST native:

- <project:#syntax/referencing>, [][syntax], [Explicit text][syntax]
- [](<#my other term>)
- <project:../intro.md>, [Explicit text](../intro.md)
- <path:example.txt>, [Explicit text](example.txt)
- <project:#mypackage.MyClass>, [Explicit text](#mypackage.MyClass)
- <inv:#*Sphinx>, [Explicit text](#sphinx.application.Sphinx)
- <inv:sphinx#code-examples>, [Explicit text](inv:sphinx#code-examples)

[syntax]: #syntax/referencing
```

--------------------------------

### Ordered List Styling (Upper Roman)

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/attributes.md

Example of an ordered list using upper-roman styling.

```markdown
1. a
2. b
. {style=upper-roman}
```

--------------------------------

### Code Fence Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Code enclosed in 3 or more backticks (`) or tildes (~), with an optional language name.

```markdown
```python
print('this is python')
```
```

--------------------------------

### Enumerated List Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_syntax_elements.md

An enumerated list with various numbering styles and a paragraph in between.

```markdown
1. *foo*

1) bar

para

10. starting
11. enumerator
```

--------------------------------

### MyST Math Block Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Multi-line math content enclosed by `$$` or `\[`...`\]` characters.

```latex
$$
a=1
$$
```

--------------------------------

### Build Documentation with Make

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/contributing.md

Clean previous builds and generate the HTML documentation strictly, checking for errors.

```shell
>> cd MyST-Parser/docs
>> make clean
>> make html-strict
```

--------------------------------

### Ordered List Styling (Lower Alpha)

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/attributes.md

Example of an ordered list using lower-alpha styling.

```markdown
1. a
2. b
. {style=lower-alpha}
```

--------------------------------

### MyST Heading Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Level 1-6 headings denoted by the number of `#` symbols.

```markdown
### Heading level 3
```

--------------------------------

### RawText Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Represents any plain text content that does not fall into other specific token categories.

```md
any text
```

--------------------------------

### Unknown Directive Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/myst-config.txt

Demonstrates an unknown directive type within a fenced code block, resulting in a system warning.

```unknown
```unknown
```
```

--------------------------------

### Example of Nested Colon Fences

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Demonstrates nesting of directives using colon fences, including admonitions within other directives.

```markdown
:::::{myst-example}

::::{important}
:::{note}
This text is **standard** _Markdown_
:::
::::

:::::
```

--------------------------------

### Ordered List Styling (Lower Roman)

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/attributes.md

Example of an ordered list using lower-roman styling.

```markdown
1. a
2. b
. {style=lower-roman}
```

--------------------------------

### Link Definition Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

A substitution for an inline link, with a reference target and optional title.

```markdown
[key]: https://www.google.com "a title"
```

--------------------------------

### MyST Table Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Standard markdown table style with pipe separation.

```markdown
| a    | b    |
| :--- | ---: |
| c    | d    |
```

--------------------------------

### Link Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Represents hyperlinks. Supports direct URL targets with optional titles, or reference-style links using keys.

```md
[text](target "title") or [text][key]
```

--------------------------------

### Build Documentation (Incremental)

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Perform an incremental build of the project documentation. This is faster for development as it only rebuilds changed files.

```bash
tox -e docs-update
```

--------------------------------

### Python Doctest Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/sourcedirs/gettext/index.md

Presents a Python doctest block, which includes a Python interactive prompt and its expected output. This is useful for embedding runnable tests within documentation.

```python
>>> print('doctest block')
doctest block
```

--------------------------------

### EscapeSequence Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Used for escaped symbols to prevent them from being interpreted as other syntax elements.

```md
\*
```

--------------------------------

### Configure Linkify Fuzzy Links

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Set myst_linkify_fuzzy_links=False to only match URLs that start with a schema (e.g., http://example.com).

```python
myst_linkify_fuzzy_links = False
```

--------------------------------

### MyST Block Break Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Defines blocks of text using `+++` with optional metadata.

```markdown
+++
{"meta": "data"}
+++
```

--------------------------------

### Build Documentation (Clean)

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Perform a clean build of the project documentation. This removes old build artifacts before generating new ones.

```bash
tox -e docs-clean
```

--------------------------------

### Markdown with cumulative attributes

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Demonstrates how attributes are cumulative and how classes are combined. This example shows the equivalence of multiple attribute sets to a single, combined set.

```markdown
```markdown
{#id1 .class1 key1="value1"}
{#id2 .class2 key2="value2"}
block

[inline]{#id2 .class2 key2="value2"}{#id1 .class1 key1="value1"}
```

is equivalent to:

```markdown
{#id2 .class1 .class2 key1="value1" key2="value2"}
block

[inline]{#id2 .class1 .class2 key1="value1" key2="value2"}
```
```

--------------------------------

### HTML Table for Sphinx Theming

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/tables.md

An example of an HTML table structure with CSS classes for alignment, intended for use with Sphinx HTML themes.

```html
<table class="colwidths-auto table">
  <thead>
    <tr><th class="text-left head"><p>left</p></th></tr>
  </thead>
  <tbody>
    <tr><td class="text-left"><p>a</p></td></tr>
  </tbody>
</table>
```

--------------------------------

### Display Math with Equation Environment

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates display math rendering using \\\\[ ... \\\\] with the \\texttt{equation} environment.

```latex
\\\\[\\begin{equation} b=2 \\end{equation}\\\]
```

--------------------------------

### Inline Substitution Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Use Jinja2 syntax {{ key_name }} to insert substitutions inline within your MyST content.

```myst
Inline: {{ key1 }}
```

--------------------------------

### Image Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Used to include images. Supports standard Markdown syntax and can optionally include a title. HTML syntax can also be used for size attributes.

```md
![alt](src "title")
```

--------------------------------

### Example GitHub Issue Link

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Illustrates a link using the 'gh-issue' scheme, which is converted to a GitHub issue URL with associated title and classes.

```markdown
<gh-issue:639>
```

--------------------------------

### Using Substitution References

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

Demonstrates the use of the `sub-ref` role to insert dynamic content like date and reading time.

```markdown
> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
```

--------------------------------

### Display Math with Align Environment

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates display math rendering using \\\\[ ... \\\\] with the \\texttt{align} and \\texttt{aligned} environments for multiple equations.

```latex
\\\\[ \\begin{align}\\\\begin{aligned}c=3\\d=4\\end{aligned}\\\\end{align} \\\\]
```

--------------------------------

### InlineCode Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Represents literal text, typically used for short code snippets or commands within a line.

```md
`a=1`
```

--------------------------------

### Block Code Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_syntax_elements.md

A simple block of code without a specified language. This is often used for plain text or generic code snippets.

```none
foo
```

--------------------------------

### Thematic Break Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Creates a horizontal line in the output.

```markdown
---

```

--------------------------------

### Link to Auto-Generated Header Anchor

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Example of creating a markdown link to an auto-generated header anchor using the syntax [](#header-anchor).

```markdown
:::{myst-example}
[](#auto-generated-header-anchors)
:::
```

--------------------------------

### Build Documentation with Specific Builder

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Build the project documentation using a specific Sphinx builder, such as 'linkcheck'. This allows for specialized documentation checks.

```bash
BUILDER=linkcheck tox -e docs-update
```

--------------------------------

### MyST Admonition Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

An alternative approach for admonition style directives, allowing content to be rendered in standard markdown editors.

```markdown
:::{note}
*content*
:::
```

--------------------------------

### Deeply Nested Directives

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

An example of deeply nested directives, demonstrating how to manage varying tick-line lengths to ensure correct parsing of multiple levels of nested blocks.

```markdown
``````{note}
The next info should be nested
`````{warning}
Here's my warning
````{admonition}
```python
# All this fuss was about this boring python?!
print('yep!')
```
````
`````
``````
```

--------------------------------

### Run Black and Flake8 Separately

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/contributing.md

Manually run the Black formatter and Flake8 linter on the project files.

```shell
>> black .
>> flake8 .
```

--------------------------------

### MyST Line Comment Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

A commented line in MyST Markdown.

```latex
% this is a comment
```

--------------------------------

### Include Specific Section of Python Code File

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/code_and_apis.md

Includes a specific section of an external Python file ('examples/example.py') defined by start and end markers using 'literalinclude'.

```python
```{literalinclude} examples/example.py
:start-after: start example
:end-before: end example
```
```

--------------------------------

### Shorthand for Simple Directives

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

A concise syntax for directives that require no arguments and no options, allowing content to start immediately after the directive name. Useful for simple notes or tips.

```markdown
```{note} Notes require **no** arguments, so content can start here.
```
```

--------------------------------

### Block Quote Example

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_syntax_elements.md

A standard block quote containing emphasized text.

```markdown
> *foo*
```

--------------------------------

### MyST Footnote Reference Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

References a footnote defined elsewhere in the document.

```markdown
[^abc]
```

--------------------------------

### Using the Math Role

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

Demonstrates the use of the `math` role for inline mathematical expressions.

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

--------------------------------

### Python Code Block with Caption and Options

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/code_and_apis.md

Adds a caption, emphasizes lines, and sets the starting line number for a Python code block using the 'code-block' directive.

```python
```{code-block} python
:caption: This is a caption
:emphasize-lines: 2,3
:lineno-start: 1

a = 1
b = 2
c = 3
```
```

--------------------------------

### Running Pytest for Regression Tests

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/test_infrastructure.md

Command to run pytest, specifically targeting tests related to 'test_example'. This command will initially fail if expected output files do not exist and generate them.

```console
$ pytest -k test_example
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Execute all pre-commit hooks on all files in the repository. This is a final check to ensure code style and quality before committing.

```bash
pre-commit run --all-files
```

--------------------------------

### Tabbed Content using Sphinx-Design

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Demonstrates how to create tabbed content panels using the 'tab-set' and 'tab-item' directives from the 'sphinx-design' extension.

```markdown
::::::

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

::::::
```

--------------------------------

### RST Directive Option

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_directives.md

Example of using the `rst:directive:option` directive in reStructuredText.

```rst
.. rst:directive:option:: a

```

--------------------------------

### See Also Directive

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/sphinx_directives.md

Adds a 'See Also' section to the documentation. Use this to link to related topics or functions.

```rst
.. seealso::

   a
```

--------------------------------

### MyST Footnote Definition Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

A definition for a referencing footnote, placed at the bottom of the document.

```markdown
[^ref]: Some footnote text
```

--------------------------------

### Code fence with lineno-start and emphasize-lines attributes

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Shows how to use 'lineno-start' and 'emphasize-lines' attributes for code fences to control line numbering and highlighting.

```markdown
:::{myst-example}
{lineno-start=1 emphasize-lines="2,3"}
```python
a = 1
b = 2
c = 3
```
:::
```

--------------------------------

### Footnote Configuration Options

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Shows Python configuration options to modify footnote sorting and transition behavior.

```python
myst_footnote_sort = False
myst_footnote_transition = False
```

--------------------------------

### Task List Items

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Shows how to create task lists with unchecked and checked items using the tasklist extension.

```markdown
- [ ] An item that needs doing
- [x] An item that is complete
```

--------------------------------

### Referencing Equations with Math Role

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

Shows how to use the `math` role with a label for referencing equations.

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

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

--------------------------------

### Indented Code Block Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Code block denoted by indentation of 4 spaces or a tab.

```markdown
    included as literal *text*
```

--------------------------------

### Live Preview Configuration

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/live-preview.md

This YAML configuration specifies MyST parser extensions and settings for the live preview. It enables extensions like colon_fence, deflist, and dollarmath, sets heading anchor levels, and activates code block highlighting.

```yaml
myst_enable_extensions:
- colon_fence
- deflist
- dollarmath
myst_heading_anchors: 2
myst_highlight_code_blocks: true
```

--------------------------------

### Formatting with Ruff

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Apply code formatting using Ruff. This command ensures consistent code style across the project.

```bash
tox -e ruff-fmt
```

--------------------------------

### Configure Intersphinx Extension

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

To load external inventories, enable the `sphinx.ext.intersphinx` extension and configure `intersphinx_mapping` in your Sphinx project.

```python
extensions = ["myst_parser", "sphinx.ext.intersphinx"]
intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
}
```

--------------------------------

### Directive with Options

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/roles-and-directives.md

Demonstrates how to use key-value options within a directive, such as setting line numbers and emphasizing specific lines in a code block. Options are prefixed with a colon.

```markdown
```{code-block}
python
:lineno-start: 10
:emphasize-lines: 1, 3

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

--------------------------------

### Forced Line Break

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Creates a line break without starting a new paragraph using a backslash.

```markdown
**Fleas** \
Adam \
Had 'em.
```

--------------------------------

### Autolinks for Various Destinations

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Demonstrates autolinks for external URLs, internal project targets, file references, and intersphinx references. Ensure the destination format matches the expected resolution rules.

```markdown
<https://example.com>
<project:#cross-references>
<project:../intro.md>
<project:../intro.md#-get-started>
<path:example.txt>
<inv:sphinx:std#index>
```

--------------------------------

### Block Level Substitution Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Insert substitutions as block-level elements, such as within directives or other Markdown structures.

```myst
Block level:

{{ key2 }}
```

--------------------------------

### Comment Splitting Paragraphs Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Shows how comments, being block-level entities, can split paragraphs in MyST Markdown.

```myst
a line
% a comment
another line
```

--------------------------------

### Markdown Link

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates a link to a URL.

```markdown
linkify URL: [www.example.com](http://www.example.com)
```

--------------------------------

### MyST Directive Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Directives are enclosed in 3 or more backticks followed by the directive name wrapped in curly brackets `{}`.

```markdown
```{
directive}
:option: value

content
```
```

--------------------------------

### reStructuredText toctree Directive

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/background.md

Example of the equivalent 'toctree' directive in reStructuredText. This demonstrates the parallel syntax with MyST markdown.

```rst
.. toctree::

   My page name <page1>
   page2
```

--------------------------------

### MyST Markdown toctree Directive

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/develop/background.md

Example of how to write a 'toctree' directive in MyST markdown. This is equivalent to the reStructuredText syntax.

```markdown
```{toctree}
My page name <page1>
page2
```
```

--------------------------------

### Smart Quotes and Replacements

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Illustrates the use of smart quotes and common symbol replacements.

```markdown
Smart-quotes 'single quotes' and "double quotes".

+-, --, ---, ... and other replacements.
```

--------------------------------

### Docutils Configuration for MyST Inventories

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Configure MyST inventories directly in the `docutils.conf` file for external inventory loading.

```ini
[general]
myst-inventories:
  sphinx: ["https://www.sphinx-doc.org/en/master", null]
```

--------------------------------

### Basic Python Code Block

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/code_and_apis.md

Demonstrates a basic Python code block with language identification for syntax highlighting.

```python
from a import b
c = "string"
```

--------------------------------

### Card Component using Sphinx-Design

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Illustrates the creation of a card component with a title, header, content, and footer using the 'sphinx-design' extension.

```markdown
::::
:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::
::::
```

--------------------------------

### Heading Level 3

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Demonstrates a level 3 heading using Markdown syntax.

```markdown
### Heading Level 3
```

--------------------------------

### LineBreak Token Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/reference.md

Represents either a soft or hard line break. A hard break is indicated by a trailing backslash.

```md
A hard break\

```

--------------------------------

### Python Code Highlighting with Line Numbers

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/attributes.md

Demonstrates Python code with line number highlighting enabled, emphasizing specific lines.

```python
a = 1
b = 2
c = 3
```

--------------------------------

### Extended Footnote Definition Example

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Illustrates how indented text following a footnote definition is included, including nested block elements.

```myst
A longer footnote definition.[^mylongdef]

[^mylongdef]: This is the _**footnote definition**_.

    That continues for all indented lines

    - even other block elements

    Plus any preceding unindented lines,
that are not separated by a blank line

This is not part of the footnote.
```

--------------------------------

### Direct LaTeX Math Environments

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/math.md

With the `amsmath` extension enabled, you can directly use LaTeX math environments like `gather` and `align`. Environments ending with `*` (e.g., `gather*`) will not be numbered.

```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}
```

--------------------------------

### Configuring Autodoc2 Docstring Parser Regexes

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/code_and_apis.md

Configure `sphinx-autodoc2` to use MyST docstrings by setting `autodoc2_docstring_parser_regexes`. This example shows how to render all docstrings as Markdown.

```python
autodoc2_docstring_parser_regexes = [
    # this will render all docstrings as Markdown
    (r".*", "myst"),
    # this will render select docstrings as Markdown
    (r"mypackage\.mymodule\..*", "myst"),
]
```

--------------------------------

### Use the tab-set directive with sphinx-design

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Example of using the 'tab-set' and 'tab-item' directives from sphinx-design to create tabbed content within a MyST Markdown file.

```markdown
::::::{myst-example}

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

::::::
```

--------------------------------

### Sphinx Integration Flow Diagram

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Visualizes the initialization, configuration, parsing, and resolution phases of the MyST Parser within the Sphinx build system.

```mermaid
flowchart TB
    subgraph init["Initialization"]
        setup["setup() in __init__.py"]
        setup_sphinx["setup_sphinx()"]
    end

    subgraph config["Configuration"]
        builder_init["builder-inited"]
        create_config["create_myst_config()"]
    end

    subgraph parse["Parse Phase"]
        source["Source .md file"]
        mdit["markdown-it-py parser"]
        tokens["Token stream"]
        renderer["DocutilsRenderer/SphinxRenderer"]
        doctree["Docutils doctree"]
    end

    subgraph resolve["Resolution Phase"]
        post_transform["MystReferenceResolver"]
        resolved["Resolved doctree"]
    end

    setup --> setup_sphinx
    setup_sphinx --> builder_init
    builder_init --> create_config

    source --> mdit --> tokens --> renderer --> doctree
    doctree --> post_transform --> resolved

    create_config -.->|"MdParserConfig"| renderer

    style create_config fill:#e1f5fe
    style renderer fill:#e1f5fe
    style post_transform fill:#e1f5fe
```

--------------------------------

### Use the card directive with sphinx-design

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Example of using the 'card' directive from sphinx-design within a MyST Markdown file to create a structured card component.

```markdown
::::{myst-example}
:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::
::::
```

--------------------------------

### Substitution for URL Formatting

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Use string formatting methods within substitutions to construct URLs dynamically, as direct substitution in URLs is not supported.

```myst
{{ '[a link](https://{}.com)'.format(key4) }}
```

--------------------------------

### Simple Variable Assignment

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes_text.txt

Demonstrates basic variable assignment in a plain text context.

```text
a=1
```

```text
x=5
```

```text
x=5
```

```text
a=1
```

```text
c=3
```

```text
c=3  d=4
```

--------------------------------

### Define Document Frontmatter

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/configuration.md

Specify document-specific metadata and options using YAML frontmatter at the beginning of a MyST document. The frontmatter must start and end with '---'.

```yaml
---
key1: value
key2: [value1, value2]
key3:
  subkey1: value
---
```

--------------------------------

### Missing Path for Include Directive

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/mock_include_errors.md

Demonstrates the error when the include directive is used without any path specified. The directive requires at least one argument.

```markdown
```include
```
```

--------------------------------

### Role Directive with Raw Role

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/docutil_directives.md

Demonstrates using the 'role' directive to define a custom role, specifically a raw role for LaTeX output. The content is then used with the custom role.

```rst
.. role:: raw-latex(raw)
   :format: latex

{raw-latex}`\tag{content}`
```

--------------------------------

### Custom CSS Class Container

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Example of wrapping content in a container with a custom CSS class using the 'colon_fence' extension. This allows for custom styling of blocks.

```markdown
::::
:::bg-primary
This is a container with a custom CSS class.

- It can contain multiple blocks
:::
::::
```

--------------------------------

### Include with Front Matter

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/mock_include.md

Demonstrates that front matter in an included file is not rendered. Only the content after the front matter is included.

```markdown
```{include} fmatter.md
```
```

--------------------------------

### Standard Option Flags in Code Block

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/directive_parsing.txt

Shows a 'code-block' directive using standard option flags like 'linenos' and 'lineno-start'.

```myst
```{code-block}
   :linenos:
   :lineno-start: 2
   :force:

body
```
```

--------------------------------

### Code Block with Line Numbering and Highlighting

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/code_and_apis.md

Applies specific line numbering start and highlights lines within a Python code block using block attributes.

```python
{lineno-start=1 emphasize-lines="2,3"}
```python
a = 1
b = 2
c = 3
```
```

--------------------------------

### Inline Links with Implicit Text

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/cross-referencing.md

Shows how to create inline links where the link text is implicitly determined by the destination. This is useful when the destination itself (like a heading or caption) can serve as descriptive text.

```markdown
[](https://example.com)
[](#cross-references)
[](../intro.md)
[](../intro.md#-get-started)
[](example.txt)
[](inv:sphinx:std#index)
```

--------------------------------

### Live Preview Input Text

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/live-preview.md

This is the MyST Markdown content that will be rendered live. It includes various MyST features like headings, notes, links, code blocks, definition lists, math, figures, and tables.

```markdown
# Heading 1

Hallo world!

```{note}
An admonition note!
```

[Link to the heading](#heading-1)

## Code

```python
from package import module
module.call("string")
```

## Definition list

term
: definition

## Math

$$\pi = 3.14159$$

## Figures

```{figure} https://via.placeholder.com/150
:width: 100px
:align: center

Figure caption
```

## Tables

```{list-table}
:header-rows: 1
:align: center

* - Header 1
  - Header 2
* - Item 1 a
  - Item 2 a
* - Item 1 b
  - Item 2 b
```
```

--------------------------------

### Inline attributes for image and reference

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Applies 'id', 'class', 'width', 'height', and 'align' attributes to an image and demonstrates referencing it.

```markdown
- ![An image with attribute](img/fun-fish.png){#imgid .bg-warning w=100px align=center}
  {ref}`a reference to the image <imgid>`
```

--------------------------------

### Non-Existent Path for Include Directive

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/mock_include_errors.md

Illustrates the error when the include directive points to a file that does not exist. The parser will report a file not found error.

```markdown
```include
other.md
```
```

--------------------------------

### Nested Parse Warning

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/reporter_warnings.md

This example shows a parse warning occurring within a nested directive. The warning pertains to an unknown interpreted text role inside the 'note' directive.

```markdown
```{note}
:class: abc
:name: xyz

{unknown}`a`
```
```

--------------------------------

### Definition list as glossary

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Converts a definition list into a glossary by adding the '.glossary' class attribute. Also shows a term reference.

```markdown
:::{myst-example}
{.glossary}
term name
: Definition of the term

{term}`term name`
:::
```

--------------------------------

### Admonition with CSS Classes and Name Option

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Shows how to apply custom CSS classes and a reference name to an admonition. The 'name' option allows for cross-referencing.

```markdown
::::
:::{tip}
:class: myclass1 myclass2
:name: a-tip-reference
Let's give readers a helpful hint!
:::

[Reference to my tip](#a-tip-reference)
::::
```

--------------------------------

### Cross-File Link to Header Anchor

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Demonstrates creating a cross-file markdown link to a header anchor using the syntax [](path/to/file.md#header-anchor).

```markdown
:::{myst-example}
[**link text**](./typography.md#headings)
:::
```

--------------------------------

### Numbered Code Block

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates a numbered code block.

```python
1type Result = "pass" | "fail"
```

--------------------------------

### Definition List with Glossary Class

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Shows how to add a 'glossary' class to a definition list using the attrs_block extension for referencing terms.

```myst
{.glossary}
my term
: Definition of the term

{term}`my term`
```

--------------------------------

### Nested Lists

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Demonstrates nested bullet points and numbered lists using standard Markdown syntax.

```markdown
- Lists can start with `-` or `*`
  * My other, nested
  * bullet point list!

1. My numbered list
2. has two points
```

--------------------------------

### Ordered list with style attribute

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Demonstrates the 'style' attribute for ordered lists, allowing control over numbering format (decimal, alpha, roman).

```markdown
:::{myst-example}
{style=lower-alpha}
1. a
2. b

{style=upper-alpha}
1. a
2. b

{style=lower-roman}
1. a
2. b

{style=upper-roman}
1. a
2. b
:::
```

--------------------------------

### Define Substitutions in conf.py

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Define substitutions in conf.py using the myst_substitutions dictionary. Keys in front-matter will override these.

```python
myst_substitutions = {
  "key1": "I'm a **substitution**"
}
```

--------------------------------

### Field Lists for API Docstrings

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Demonstrates using field lists for API docstrings, a common use case in Sphinx for documenting parameters, types, and return values.

```python
```{py:function} send_message(sender, priority)

Send a message to a recipient

:param str sender: The person sending the message
:param priority: The priority of the message, can be a number 1-5
:type priority: int
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
```
```

--------------------------------

### MyST Parser Pipeline Stages

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Visual representation of the MyST parser's three-stage pipeline, showing the transformation from MyST Markdown to docutils AST and finally to Sphinx/HTML output.

```text
MyST Markdown → markdown-it tokens → docutils AST → Sphinx/HTML output
```

--------------------------------

### Admonition Directive with Options

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/myst-config.txt

Illustrates the 'admonition' directive with custom attributes and options, including a warning for unknown option keys.

```admonition
```admonition title
content
```
```

--------------------------------

### Inline attributes for literal and reference

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Applies 'id' and 'class' attributes to a literal code block and demonstrates referencing it.

```markdown
- `A literal with attributes`{#literalid .bg-warning},
  {ref}`a reference to the literal <literalid>`
```

--------------------------------

### Enable AmS-LaTeX Math Parsing

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Add `"amsmath"` to `myst_enable_extensions` to enable direct parsing of AmS-LaTeX environments.

```python
myst_enable_extensions = ["amsmath"]
```

--------------------------------

### Custom Attributes and Options in Admonition

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/myst-config.txt

Shows how to apply custom names, classes, and options to an admonition directive.

```myst
{#myname .class1}
{a=b}
```

--------------------------------

### Inline and Block Math Syntax

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Use single dollar signs for inline math and double dollar signs for block math. This is equivalent to using the math directive.

```markdown
Inline math: `$...$`
Display (block) math: `$$...$$`
```

```markdown
{math}`x_{hey}=it+is^{math}`
```

--------------------------------

### Alternate Numbering Styles for Lists

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/typography.md

Demonstrates different numbering styles (alpha, roman) for ordered lists using attributes.

```markdown
{style=lower-alpha}
1. a
2. b

{style=upper-alpha}
1. a
2. b

{style=lower-roman}
1. a
2. b

{style=upper-roman}
1. a
2. b
```

--------------------------------

### Parse Markdown to HTML with myst-docutils-demo

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/intro.md

Use the myst-docutils-demo CLI tool to parse a basic Markdown file into HTML. This demonstrates basic MyST to HTML conversion.

```markdown
:::{myst-to-html}
# My nifty title

Some **text**!
:::
```

--------------------------------

### Include file from outside docs folder with relative paths

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/faq/index.md

Include files from outside the docs directory, like README.md, using the `include` directive. The `relative-docs` and `relative-images` options can help resolve local links and image paths correctly.

```markdown
```{include} ../../example.md
:relative-docs: docs/
:relative-images:
```
```

--------------------------------

### Enable Linkify Extension

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

To enable automatic identification of bare web URLs and convert them to hyperlinks, add "linkify" to myst_enable_extensions in your conf.py.

```python
myst_enable_extensions = [
    "linkify",
]
```

--------------------------------

### Programmatic MyST Parsing with Docutils API

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/docutils.md

Illustrates how to use the myst_parser.docutils_.Parser class with Docutils' publish_string for programmatic conversion.

```python
from docutils.core import publish_string
from myst_parser.docutils_ import Parser

source = "hallo world\n: Definition"
output = publish_string(
    source=source,
    writer_name="html5",
    settings_overrides={
        "myst_enable_extensions": ["deflist"],
        "embed_stylesheet": False,
    },
    parser=Parser(),
)
```

--------------------------------

### Run Tests with Specific Python/Sphinx Version

Source: https://github.com/executablebooks/myst-parser/blob/master/AGENTS.md

Execute tests using a specific combination of Python and Sphinx versions. This is crucial for ensuring compatibility.

```bash
tox -e py311-sphinx8
```

--------------------------------

### Markdown Image

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html

Demonstrates image embedding with a caption.

```markdown
![fun-fish](_images/fun-fish.png)

This is a caption in **Markdown**
```

--------------------------------

### Inline attributes for link and reference

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/optional.md

Applies 'id' and 'class' attributes to a hyperlink and demonstrates referencing it.

```markdown
- [A link with attributes](syntax/attributes){#linkid .bg-warning},
  {ref}`a reference to the link <linkid>`
```

--------------------------------

### Custom Title Admonition

Source: https://github.com/executablebooks/myst-parser/blob/master/docs/syntax/admonitions.md

Demonstrates how to create an admonition with a custom title, including Markdown formatting within the title, and styling it as a specific admonition type using the 'class' option.

```markdown
::::
:::{admonition} My custom title with *Markdown*!
:class: tip

This is a custom title for a tip admonition.
:::
::::
```

--------------------------------

### Directive with Arguments and Content

Source: https://github.com/executablebooks/myst-parser/blob/master/tests/test_renderers/fixtures/directive_options.md

A directive that accepts arguments and content.

```markdown
```{restructuredtext-test-directive} foo
bar
```
```