or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tools.mdconfiguration.mddocument-rendering.mdindex.mdinventory-warnings.mdparsing.mdsphinx-extension.md
tile.json

tessl/pypi-myst-parser

An extended CommonMark compliant parser, with bridges to docutils and Sphinx

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/myst-parser@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-myst-parser@4.0.0

index.mddocs/

MyST-Parser

An extended CommonMark compliant parser with bridges to docutils and Sphinx. MyST-Parser provides a rich and extensible flavor of Markdown designed for technical documentation and publishing, offering comprehensive Markdown parsing that extends CommonMark with additional syntax for technical writing, including support for Sphinx directives, roles, and cross-references.

Package Information

  • Package Name: myst-parser
  • Language: Python
  • Installation: pip install myst-parser

Core Imports

import myst_parser

For Sphinx extension usage:

# Add to Sphinx conf.py extensions list
extensions = ['myst_parser']

For programmatic parsing:

from myst_parser.config.main import MdParserConfig
from myst_parser.parsers.docutils_ import Parser
from myst_parser.parsers.sphinx_ import MystParser

Basic Usage

Sphinx Extension Usage

# In Sphinx conf.py
extensions = ['myst_parser']

# Configure MyST parser options
myst_enable_extensions = [
    "deflist",
    "tasklist",
    "substitution",
    "colon_fence",
]

myst_heading_anchors = 3
myst_footnote_transition = True

Programmatic Parsing with Docutils

from myst_parser.parsers.docutils_ import Parser
from docutils.core import publish_doctree

# Create parser instance
parser = Parser()

# Parse MyST markdown to docutils document tree
source = """
# Example MyST Document

This is a MyST markdown document with {emphasis}`substitution syntax`
and support for Sphinx directives.

:::{note}
This is a note directive.
:::
"""

document = publish_doctree(source, parser=parser)
print(document.pformat())

Configuration-Driven Parsing

from myst_parser.config.main import MdParserConfig
from myst_parser.parsers.mdit import create_md_parser
from myst_parser.mdit_to_docutils.base import DocutilsRenderer, make_document

# Create custom configuration
config = MdParserConfig(
    enable_extensions={"tasklist", "deflist", "substitution"},
    heading_anchors=2,
    footnote_sort=True,
    commonmark_only=False
)

# Create document and renderer
document = make_document("example.md", parser_cls=None)
renderer = DocutilsRenderer(document)

# Create configured markdown parser
md_parser = create_md_parser(config, renderer)

# Parse markdown content
result = md_parser.render("""
# Document Title

- [x] Completed task
- [ ] Pending task

Term
: Definition of the term
""")

Architecture

MyST-Parser operates through several interconnected components:

  • Configuration System: MdParserConfig provides comprehensive control over parsing behavior, syntax extensions, and output formatting
  • Parser Layer: Separate implementations for Sphinx (MystParser) and docutils (Parser) environments
  • Markdown Processing: Built on markdown-it-py with MyST-specific extensions and token processing
  • Rendering Engine: Converts markdown-it tokens to docutils AST nodes via DocutilsRenderer and SphinxRenderer
  • Sphinx Integration: Full extension with directives, roles, reference resolution, and configuration management
  • CLI Tools: Command-line utilities for various output formats and analysis

This architecture enables MyST-Parser to serve as both a standalone Markdown processor and a comprehensive Sphinx extension for technical documentation.

Capabilities

Configuration Management

Comprehensive configuration system with MdParserConfig dataclass providing control over parsing behavior, syntax extensions, cross-references, and output formatting. Includes validation, file-level overrides, and YAML frontmatter support.

class MdParserConfig:
    commonmark_only: bool = False
    enable_extensions: set[str] = field(default_factory=set)
    heading_anchors: int = 0
    footnote_sort: bool = False
    ref_domains: Iterable[str] | None = None
    # ... 20+ additional configuration options

def merge_file_level(config: MdParserConfig, topmatter: dict, warning: Callable) -> MdParserConfig: ...
def read_topmatter(text: str) -> dict: ...

Configuration

Parsing System

Dual parser implementations for Sphinx and docutils environments, with factory functions for creating configured markdown-it-py parsers and comprehensive directive/option parsing support.

class MystParser:
    supported: tuple[str, ...] = ("md", "markdown", "myst")
    def parse(self, inputstring: str, document) -> None: ...

class Parser:
    def parse(self, inputstring: str, document) -> None: ...

def create_md_parser(config: MdParserConfig, renderer) -> MarkdownIt: ...

Parsing

Sphinx Extension

Complete Sphinx extension with setup functions, custom directives, roles, and reference resolution. Provides seamless integration with Sphinx's documentation system.

def setup(app) -> dict: ...
def setup_sphinx(app, load_parser: bool = False) -> None: ...
def create_myst_config(app) -> MdParserConfig: ...

class FigureMarkdown(SphinxDirective): ...
class SubstitutionReferenceRole(SphinxRole): ...
class MystReferenceResolver(ReferencesResolver): ...

Sphinx Extension

Document Rendering

Advanced rendering system for converting markdown-it tokens to docutils AST nodes, with specialized renderers for docutils and Sphinx environments, HTML processing, and document transformations.

class DocutilsRenderer:
    def __init__(self, document): ...
    def render(self, tokens, options, md_env, renderer=None): ...

class SphinxRenderer(DocutilsRenderer): ...

def make_document(source_path: str, parser_cls=None): ...
def token_line(token, default: int | None = None) -> int | None: ...

Document Rendering

CLI Tools

Command-line utilities for MyST document processing, including HTML, LaTeX, XML output generation, heading anchor extraction, and inventory management.

def print_anchors(args=None) -> None: ...
def inventory_cli() -> None: ...

# CLI commands available:
# myst-anchors, myst-inv, myst-docutils-html, myst-docutils-html5,
# myst-docutils-demo, myst-docutils-latex, myst-docutils-xml,
# myst-docutils-pseudoxml

CLI Tools

Inventory and Warning Systems

Sphinx inventory integration for cross-references and comprehensive warning system with categorized warning types for parsing, rendering, and reference resolution issues.

class MystWarnings(Enum):
    DEPRECATED = "deprecated"
    NOT_SUPPORTED = "not_supported"
    DIRECTIVE_PARSING = "directive_parsing"
    XREF_MISSING = "xref_missing"
    # ... 15+ additional warning types

def create_warning(document, message: str, subtype: MystWarnings, **kwargs) -> None: ...

def from_sphinx(inv) -> InventoryType: ...
def to_sphinx(inv: InventoryType): ...
def load(stream, base_url: str) -> InventoryType: ...

Inventory and Warnings

Types

Core type definitions used across the MyST-Parser API:

class MdParserConfig:
    """Main configuration dataclass for MyST parser settings."""

class TopmatterReadError(Exception):
    """Exception raised when reading YAML frontmatter fails."""

class UrlSchemeType(TypedDict):
    """Configuration for external URL schemes."""
    allowed_schemes: tuple[str, ...]
    classes: list[str]

class InventoryItemType(TypedDict):
    """Single item in a Sphinx inventory."""
    name: str
    domain: str
    role: str
    uri: str
    dispname: str

class InventoryType(TypedDict):
    """Complete Sphinx inventory data structure."""
    project: str
    version: str
    items: dict[str, InventoryItemType]

ValidatorType = Callable[[object, object, object], None]