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, append: bool = False)[source]

Context manager for temporarily setting the current node.

add_line_and_source_path(node, token)[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, destination)[source]

Create nodes for references that are not immediately resolvable.


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, 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)[source]
class myst_parser.mocking.MockState(renderer, state_machine: myst_parser.mocking.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=0, widths=None)[source]
build_table_row(rowdata, tableline)[source]
class myst_parser.mocking.MockStateMachine(renderer, 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, 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).



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.dict_to_field_list(data: dict) → docutils.nodes.field_list[source]

Render each key/val pair as a docutils field node.

If the field list is at the start of the document, then it will be converted to a docinfo node during the docutils.docutils.transforms.frontmatter.DocInfo transform (priority 340), and bibliographic keys will be converted to specific nodes:

'authors': docutils.nodes.authors,
'organization': docutils.nodes.organization,
'address': docutils.nodes.address,
'version': docutils.nodes.version,
'revision': docutils.nodes.revision,
'status': docutils.nodes.status,
'copyright': docutils.nodes.copyright,
'dedication': docutils.nodes.topic,
'abstract': docutils.nodes.topic}

If using sphinx, this docinfo node will later be extracted from the AST, by the DoctreeReadEvent transform (priority 880), calling MetadataCollector.process_doc. In this case keys and values will be converted to strings and stored in app.env.metadata[app.env.docname]

See for docinfo fields used by sphinx.

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.