myst_parser.parsers.directives Namespace Reference

Classes
class	_DirectiveOptions
class	DirectiveParsingResult
class	ParseWarnings

Functions
DirectiveParsingResult	parse_directive_text (type[Directive] directive_class, str first_line, str content, *int|None line=None, bool validate_options=True, dict[str, str]|None additional_options=None)
_DirectiveOptions	_parse_directive_options (str content, type[Directive] directive_class, bool as_yaml, int|None line, dict[str, str]|None additional_options=None)
list[str]	parse_directive_arguments (type[Directive] directive_cls, str arg_text)

Detailed Description

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.

Function Documentation

_parse_directive_options()

_DirectiveOptions myst_parser.parsers.directives._parse_directive_options ( str  content, type[Directive]  directive_class, bool  as_yaml, int | None  line, dict[str, str] | None   additional_options = None  )

protected

Parse (and validate) the directive option section.

:returns: (content, options, validation_errors)

parse_directive_arguments()

list[str] myst_parser.parsers.directives.parse_directive_arguments	(	type[Directive]	directive_cls,
		str	arg_text
	)

Parse (and validate) the directive argument section.

parse_directive_text()

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

Parse (and validate) the full directive text.

:param first_line: The text on the same line as the directive name.
    May be an argument or body text, dependent on the directive
:param content: All text after the first line. Can include options.
:param 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.
:param 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