MyST Renderers

These renderers take the markdown-it parsed token stream and convert it to the docutils AST. The sphinx renderer is a subclass of the docutils one, with some additional methods only available via sphinx .e.g. multi-document cross-referencing.


class myst_parser.docutils_renderer.DocutilsRenderer(parser: markdown_it.main.MarkdownIt)[source]

Bases: object

A markdown-it-py renderer to populate (in-place) a docutils.document AST.

Note, this render is not dependent on Sphinx.

__output__ = 'docutils'
__init__(parser: markdown_it.main.MarkdownIt)[source]

Load the renderer (called by MarkdownIt)

render(tokens: List[markdown_it.token.Token], options, env: markdown_it.utils.AttrDict)[source]

Run the render on a token stream.

  • tokens – list on block tokens to render

  • options – params of parser instance

  • env – the environment sandbox associated with the tokens, containing additional metadata like reference info

nested_render_text(text: str, lineno: int)[source]

Render unparsed text.

current_node_context(node: docutils.nodes.Element, append: bool = False)[source]

Context manager for temporarily setting the current node.

add_line_and_source_path(node, token: Union[markdown_it.token.Token, markdown_it.token.NestedTokens])[source]

Copy the line number and document source path to the docutils node.


class myst_parser.sphinx_renderer.SphinxRenderer(parser: markdown_it.main.MarkdownIt)[source]

Bases: myst_parser.docutils_renderer.DocutilsRenderer

A markdown-it-py renderer to populate (in-place) a docutils.document AST.

This is sub-class of DocutilsRenderer that handles sphinx specific aspects, such as cross-referencing.

__output__ = 'docutils'
handle_cross_reference(token: markdown_it.token.Token, destination: str)[source]

Create nodes for references that are not immediately resolvable.

render_math_block_eqno(token: markdown_it.token.Token)[source]

Render math with referencable labels, e.g. $a=1$ (label).


These classes are parsed to sphinx roles and directives, to mimic the original docutls rST specific parser elements, but instead run nested parsing with the markdown parser.

class myst_parser.mocking.MockInliner(renderer: DocutilsRenderer, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.Inliner.

This is parsed to role functions.

problematic(text: str, rawsource: str, message: docutils.nodes.system_message) → docutils.nodes.problematic[source]
class myst_parser.mocking.MockState(renderer: DocutilsRenderer, state_machine: MockStateMachine, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.RSTState.

This is parsed to the method, so that they may run nested parses on their content that will be parsed as markdown, rather than RST.

parse_directive_block(content: docutils.statemachine.StringList, line_offset: int, directive: Type[docutils.parsers.rst.Directive], option_presets: dict) → Tuple[list, dict, docutils.statemachine.StringList, int][source]

Parse the full directive text


(arguments, options, content, content_offset)

nested_parse(block: docutils.statemachine.StringList, input_offset: int, node: docutils.nodes.Element, match_titles: bool = False, state_machine_class=None, state_machine_kwargs=None)None[source]

Perform a nested parse of the input block, with node as the parent.

parse_target(block, block_text, lineno: int)[source]

Taken from # noqa: E501

inline_text(text: str, lineno: int) → Tuple[List[docutils.nodes.Element], List[docutils.nodes.Element]][source]

Parse text with only inline rules.


(list of nodes, list of messages)

attribution_pattern = re.compile('^((?:---?(?!-)|—) *)(.+)')
block_quote(lines: List[str], line_offset: int) → List[docutils.nodes.Element][source]

Parse a block quote, which is a block of text, followed by an (optional) attribution.

No matter where you go, there you are.

-- Buckaroo Banzai
build_table(tabledata, tableline, stub_columns: int = 0, widths=None)[source]
build_table_row(rowdata, tableline)[source]
class myst_parser.mocking.MockStateMachine(renderer: DocutilsRenderer, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.RSTStateMachine.

This is parsed to the method.

get_source(lineno: Optional[int] = None)[source]

Return document source path.

get_source_and_line(lineno: Optional[int] = None)[source]

Return (source path, line) tuple for current or given line number.

class myst_parser.mocking.MockIncludeDirective(renderer: DocutilsRenderer, name: str, klass: docutils.parsers.rst.directives.misc.Include, arguments: list, options: dict, body: List[str], lineno: int)[source]

Bases: object

This directive uses a lot of statemachine logic that is not yet mocked. Therefore, we treat it as a special case (at least for now).


run() → List[docutils.nodes.Element][source]
add_name(node: docutils.nodes.Element)[source]

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

Additional Methods

myst_parser.docutils_renderer.make_document(source_path='notset') → docutils.nodes.document[source]

Create a new docutils document.

myst_parser.docutils_renderer.html_meta_to_nodes(data: Dict[str, Any], document: docutils.nodes.document, line: int, reporter: docutils.utils.Reporter) → List[Union[docutils.nodes.pending, docutils.nodes.system_message]][source]

Replicate the meta directive, by converting a dictionary to a list of pending meta nodes


myst_parser.sphinx_renderer.minimal_sphinx_app(configuration=None, sourcedir=None, with_builder=False, raise_on_warning=False)[source]

Create a minimal Sphinx environment; loading sphinx roles, directives, etc.

myst_parser.sphinx_renderer.mock_sphinx_env(conf=None, srcdir=None, document=None, with_builder=False, raise_on_warning=False)[source]

Set up an environment, to parse sphinx roles/directives, outside of a sphinx-build.

  • conf – a dictionary representation of the sphinx

  • srcdir – a path to a source directory (for example, can be used for include statements)

This primarily copies the code in sphinx.util.docutils.docutils_namespace and sphinx.util.docutils.sphinx_domains.