myst_parser.parsers.directives#

Fenced code blocks are parsed as directives, if the block starts with {directive_name}, followed by arguments on the same line.

Directive options are read from a YAML block, if the first content line starts with ---, e.g.

```{directive_name} arguments
---
option1: name
option2: |
    Longer text block
---
content...
```

Or the option block will be parsed if the first content line starts with :, as a YAML block consisting of every line that starts with a :, e.g.

```{directive_name} arguments
:option1: name
:option2: other

content...
```

If the first line of a directive’s content is blank, this will be stripped from the content. This is to allow for separation between the option block and content.

1.  Module Contents#

1.1.  Classes#

DirectiveParsingResult

1.2.  Functions#

parse_directive_text

Parse (and validate) the full directive text.

parse_directive_options

Parse (and validate) the directive option section.

parse_directive_arguments

Parse (and validate) the directive argument section.

1.3.  API#

class myst_parser.parsers.directives.DirectiveParsingResult[source]#
arguments: list[str] = None#

The arguments parsed from the first line.

options: dict = None#

Options parsed from the YAML block.

body: list[str] = None#

The lines of body content

body_offset: int = None#

The number of lines to the start of the body content.

warnings: list[str] = None#

List of non-fatal errors encountered during parsing.

myst_parser.parsers.directives.parse_directive_text(directive_class: type[docutils.parsers.rst.Directive], first_line: str, content: str, *, validate_options: bool = True, additional_options: dict[str, str] | None = None) myst_parser.parsers.directives.DirectiveParsingResult[source]#

Parse (and validate) the full directive text.

Parameters:
  • first_line – The text on the same line as the directive name. May be an argument or body text, dependent on the directive

  • content – All text after the first line. Can include options.

  • validate_options – Whether to validate the values of options

  • additional_options – Additional options to add to the directive, above those parsed from the content (content options take priority).

Raises:

MarkupError – if there is a fatal parsing/validation error

myst_parser.parsers.directives.parse_directive_options(content: str, directive_class: type[docutils.parsers.rst.Directive], validate: bool = True, additional_options: dict[str, str] | None = None) tuple[str, dict, list[str]][source]#

Parse (and validate) the directive option section.

Returns:

(content, options, validation_errors)

myst_parser.parsers.directives.parse_directive_arguments(directive_cls: type[docutils.parsers.rst.Directive], arg_text: str) list[str][source]#

Parse (and validate) the directive argument section.