MyST-Parser

MyST-Parser is a Sphinx and Docutils extension designed to parse MyST (Markedly Structured Text), a rich and extensible flavor of Markdown tailored for technical and scientific documentation.

Key features include:

• CommonMark-plus: Extends the CommonMark specification to support technical features like tables and footnotes.
• Sphinx Compatibility: Supports MyST role and directive syntax, allowing users to leverage the full power of Sphinx (e.g., admonitions, figures) and existing Sphinx extensions.
• High Configurability: Parsing behavior and extended syntax features can be modified at both the global and individual document levels.
• Underlying Engine: It uses markdown-it-py (a CommonMark-compliant parser) to transform source text into tokens.

How link text is rendered depends on whether you provide it:

• Explicit text: If you provide text like [text](#dest), that text is used. It can contain nested inline markup (e.g., [**bold**](#dest)).
• Implicit text: If no text is provided (e.g., [](#dest) or <project:#dest>), MyST attempts to resolve implicit text:
  • For headings: The heading text is used.
  • For figures/tables: The caption is used.
  • Otherwise: The destination itself is used as the text.

The MyST parser is built as a multi-stage pipeline designed to bridge MyST-flavored Markdown with the Sphinx documentation ecosystem. It operates in three primary stages:

1. Markdown-It-Py Parsing: The parser extends markdown-it-py (a CommonMark parser) to support MyST-specific syntax, such as Sphinx roles and directives. This stage produces a markdown-it token stream.
2. Docutils Rendering: A specialized docutils renderer converts the markdown-it token stream into docutils document objects.
3. Sphinx Integration: The MyST parser for Sphinx orchestrates the entire process: it parses files using the markdown-it parser (with MyST plugins), converts the result into docutils objects via the renderer, and feeds these objects into Sphinx for site building.

Roles are in-line extension points used to define arbitrary new functionality within a line of text.

Syntax: {role-name}role content`

Examples:

• Mathematical expressions: {math}a^2 + b^2 = c^2`
• References: You can use roles to reference equations or other items. For example, if an equation has a :label: euler, you can reference it using {math:numref}euler`.

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

MyST-parser is a Sphinx parser that allows you to use MyST markdown as an alternative to reStructuredText (.rst).

Because MyST-parser converts MyST markdown into the standard Sphinx document model (via docutils), any features available in reStructuredText—specifically in-line roles and block-level directives—can be implemented in MyST markdown. Once parsed, Sphinx treats MyST documents and reStructuredText documents identically.

By default, when using MyST-parser, Sphinx assumes that files with the .md extension are written in MyST markdown.

myst markdown (.md) ------> myst parser ---+
                                           |
                                           +-->Sphinx document (docutils)
                                           |
reStructuredText (.rst) --> rst parser ----+

The test suite is organized into four hierarchical layers to ensure compliance across different stages of the parsing and rendering pipeline:

1. CommonMark Compliance: Located in tests/test_commonmark, these tests run the CommonMark test set to ensure the parser adheres to the CommonMark specification.
2. AST Conversion: Located in tests/test_renderers, these tests verify that the Markdown AST is correctly converted to the docutils/sphinx AST, including the correct parsing and execution of roles and directives.
3. Sphinx Integration: Located in tests/test_sphinx, these tests verify that minimal Sphinx project builds correctly convert MyST markdown files to HTML.
4. Documentation Builds: Managed via .circleci, these tests build and test the package's own documentation (written in MyST) to catch build errors or warnings.

When myst_heading_anchors is enabled, MyST-Parser generates slugs for headings.

• Default Behavior: Follows the GitHub implementation (lowercase, punctuation removed, spaces replaced with -, and uniqueness enforced via suffixes like -1, -2).
• Customization: The slug generation function can be changed via the myst_heading_slug_func configuration option (e.g., using the "gitlab" preset).

Directives are block-level extension points in MyST used to interpret chunks of text as specific types of markup. They use a syntax similar to Markdown code fences but with curly brackets around the directive name.

Basic Syntax:

:option1: value1
:option2: value2

Directive content goes here

Key Behaviors:

• Content Parsing: MyST parses the content block of a directive as Markdown. This allows you to use Markdown links, bold text, etc., inside a directive.
• Short-hand: For directives requiring no arguments and no options, you can start the content immediately after the directive name.
• ReStructuredText Support: Use the {eval-rst} directive if you need to parse a block specifically as ReStructuredText instead of Markdown.

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

Attributes allow you to add metadata like IDs, classes, and key-value pairs to elements using curly braces {}.

Syntax Rules:

• .foo: Specifies class foo (multiple classes can be combined).
• #foo: Specifies identifier foo (the last one provided wins).
• key="value" or key=value: Specifies a key-value attribute.
• %: Starts a comment that ends at the next % or }.

Attributes are cumulative: inner attributes override outer ones, but multiple classes are merged.

Note: attrs_inline replaces the deprecated attrs_image extension.

{#id1 .class1 key1="value1"}
block

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

You can override global settings for a single document using YAML frontmatter. The configuration must be placed under the myst key at the start of the document, delimited by three or more --- markers. Local configuration takes precedence over global configuration.

---
myst:
  enable_extensions: ["deflist"]
---