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

ParseWarnings
DirectiveParsingResult

1.2.  Functions

parse_directive_text	Parse (and validate) the full directive text.
parse_directive_arguments	Parse (and validate) the directive argument section.

1.3.  API

class myst_parser.parsers.directives.ParseWarnings

msg: str = None

lineno: int | None = None

type: myst_parser.warnings_.MystWarnings = None

class myst_parser.parsers.directives.DirectiveParsingResult

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[myst_parser.parsers.directives.ParseWarnings] = None

List of non-fatal errors encountered during parsing. (message, line_number)

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

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 This is actually only here to be used by myst-nb cells, which converts options directly to JSON metadata, using the full YAML spec.

• 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_arguments(directive_cls: type[docutils.parsers.rst.Directive], arg_text: str) → list[str]

Parse (and validate) the directive argument section.