Skip to main content

Parsing and AST

multimark exposes the full abstract syntax tree (AST) that cmark-gfm builds during parsing. This lets you inspect document structure, extract content, transform nodes, and render subtrees. This is all backed by the same C library that powers the renderers.

Parsing to an AST

The parse() function takes a Markdown string and returns the root Node of the parsed tree.

from multimark import parse, NodeType

doc = parse("# Hello\n\nA paragraph with **bold** text.\n")
doc
<Node document>

The root node is always a DOCUMENT. Its children are the top-level block elements.

for child in doc.children:
    print(child)
<Node heading level=1>
<Node paragraph>

Walking the Tree

The walk() method performs a depth-first traversal, yielding (event, node) pairs. Container nodes produce both "enter" and "exit" events; leaf nodes produce only "enter".

for event, node in doc.walk():
    if event == "enter":
        print(f"{node.type_string:>15}  {node.literal or ''}")
       document  
        heading  
           text  Hello
      paragraph  
           text  A paragraph with 
         strong  
           text  bold
           text   text.

This is the primary way to scan or transform a document. For example, extracting all links:

md = "See [Python](https://python.org) and [Rust](https://rust-lang.org).\n"
doc = parse(md)

links = [
    (node.url, node.first_child.literal)
    for event, node in doc.walk()
    if event == "enter" and node.type == NodeType.LINK
]
links
[('https://python.org', 'Python'), ('https://rust-lang.org', 'Rust')]

Node Properties

Each node type exposes relevant properties. Headings have a heading_level, links have url and title, code blocks have fence_info, and text nodes have literal.

doc = parse("## Installation\n\nRun `pip install multimark`.\n")

for event, node in doc.walk():
    if event == "enter" and node.type == NodeType.HEADING:
        print(f"Level {node.heading_level}: ", end="")
        print(node.first_child.literal)
Level 2: Installation

Source positions are available on every node:

doc = parse("First paragraph.\n\nSecond paragraph.\n")

for child in doc.children:
    print(f"Lines {child.start_line}–{child.end_line}: {child.type_string}")
Lines 1–1: paragraph
Lines 3–3: paragraph

Mutating the Tree

Nodes support in-place mutation. You can change properties, add or remove nodes, and then render the modified tree.

from multimark import Node

doc = parse("Visit [example](http://example.com) for details.\n")

for event, node in doc.walk():
    if node.type == NodeType.LINK and node.url.startswith("http://"):
        node.url = node.url.replace("http://", "https://", 1)

print(doc.render_html())
<p>Visit <a href="https://example.com">example</a> for details.</p>

You can also build nodes from scratch:

doc = parse("Some content.\n")

heading = Node.new(NodeType.HEADING)
heading.heading_level = 2
text = Node.new(NodeType.TEXT)
text.literal = "Table of Contents"
heading.append_child(text)
doc.prepend_child(heading)

print(doc.render_html())
<h2>Table of Contents</h2>
<p>Some content.</p>

Rendering Subtrees

Any node can render itself independently, which is useful for extracting fragments.

doc = parse("# Title\n\nFirst paragraph.\n\nSecond paragraph.\n")

second_para = list(doc.children)[2]
print(second_para.render_html())
<p>Second paragraph.</p>

All six output formats are available: render_html(), render_xml(), render_latex(), render_man(), render_commonmark(), and render_plaintext().

print(second_para.render_plaintext())
Second paragraph.

Streaming Parser

For large documents or streamed input, the Parser class provides incremental feeding.

from multimark import Parser

with Parser(smart=True) as p:
    p.feed("# Chapter 1\n\n")
    p.feed("Some text with \"quotes\" and -- dashes.\n")
    print(p.render_html())
    print(p.render_plaintext(width=72))
<h1>Chapter 1</h1>
<p>Some text with “quotes” and – dashes.</p>

Chapter 1

Some text with “quotes” and – dashes.

The Parser also works as a context manager for automatic resource cleanup, and its finish() method returns the root Node for AST access:

with Parser(extensions=["table"]) as p:
    p.feed("| A | B |\n|---|---|\n| 1 | 2 |\n")
    doc = p.finish()
    print(doc.render_html())
<table>
<thead>
<tr>
<th>A</th>
<th>B</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>2</td>
</tr>
</tbody>
</table>

GFM Extensions with the AST

Extensions like tables, strikethrough, and task lists produce their own node types in the tree. These work with both parse() and Parser.

doc = parse(
    "- [x] Done\n- [ ] Pending\n",
    extensions=["tasklist"],
)

for event, node in doc.walk():
    if event == "enter":
        print(f"{node.type_string}: {node.literal or ''}")
document: 
list: 
tasklist: 
paragraph: 
text: Done
tasklist: 
paragraph: 
text: Pending

Common Patterns

Extract all headings for a table of contents

doc = parse("# Intro\n\n## Setup\n\n### Details\n\n## Usage\n")

toc = []
for event, node in doc.walk():
    if event == "enter" and node.type == NodeType.HEADING:
        level = node.heading_level
        text = node.first_child.literal if node.first_child else ""
        toc.append((level, text))

toc
[(1, 'Intro'), (2, 'Setup'), (3, 'Details'), (2, 'Usage')]

Strip all formatting and extract plain text

doc = parse("Hello **world**, visit [here](https://x.com).\n")

texts = [
    node.literal
    for event, node in doc.walk()
    if event == "enter" and node.type == NodeType.TEXT
]
" ".join(texts)
'Hello  world , visit  here .'

For comparison, render the same tree directly:

doc.render_plaintext()
'Hello world, visit here.\n'

The manual approach collects only TEXT nodes and joins them with spaces. The renderer also includes code contents and preserves list markers and paragraph breaks. Some GFM markers remain, and raw HTML blocks are omitted including their text. See Plain Text for the full behavior.