0
# Document Rendering
1
2
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.
3
4
## Capabilities
5
6
### Base Renderer
7
8
Core rendering functionality for converting markdown-it-py tokens to docutils Abstract Syntax Tree (AST) nodes, providing the foundation for MyST document processing.
9
10
```python { .api }
11
class DocutilsRenderer:
12
"""
13
Main markdown-it-py renderer for docutils AST.
14
15
Converts markdown-it tokens to docutils nodes, handling all standard
16
MyST syntax elements and providing extension points for custom rendering.
17
"""
18
19
def __init__(self, document) -> None:
20
"""
21
Initialize renderer with docutils document.
22
23
Args:
24
document: Docutils document node to populate
25
"""
26
27
def render(self, tokens, options, md_env, renderer=None):
28
"""
29
Render markdown-it tokens to docutils nodes.
30
31
Args:
32
tokens: List of markdown-it tokens to render
33
options: Markdown-it options
34
md_env: Markdown-it environment
35
renderer: Optional custom renderer
36
37
Returns:
38
Rendered content (typically None, modifies document in-place)
39
"""
40
41
def create_warning(
42
self,
43
message: str,
44
subtype: MystWarnings = MystWarnings.RENDER_METHOD,
45
**kwargs
46
) -> None:
47
"""
48
Create and emit a rendering warning.
49
50
Args:
51
message: Warning message
52
subtype: Warning category
53
**kwargs: Additional warning context
54
"""
55
56
def add_line_and_source_path(self, node, token) -> None:
57
"""
58
Add line number and source path to docutils node.
59
60
Args:
61
node: Docutils node to annotate
62
token: Source markdown-it token
63
"""
64
```
65
66
Usage example:
67
68
```python
69
from myst_parser.mdit_to_docutils.base import DocutilsRenderer, make_document
70
from myst_parser.parsers.mdit import create_md_parser
71
from myst_parser.config.main import MdParserConfig
72
73
# Create document and renderer
74
document = make_document("example.md")
75
renderer = DocutilsRenderer(document)
76
77
# Create configured parser
78
config = MdParserConfig(enable_extensions={"tasklist", "deflist"})
79
md_parser = create_md_parser(config, renderer)
80
81
# Parse and render content
82
source = """
83
# Document Title
84
85
- [x] Completed task
86
- [ ] Pending task
87
88
Term
89
: Definition of the term
90
"""
91
92
md_parser.render(source)
93
print(document.pformat())
94
```
95
96
### Sphinx Renderer
97
98
Specialized renderer for Sphinx environments, extending the base DocutilsRenderer with Sphinx-specific functionality and integration features.
99
100
```python { .api }
101
class SphinxRenderer(DocutilsRenderer):
102
"""
103
Sphinx-specific renderer extending DocutilsRenderer.
104
105
Provides Sphinx-specific node handling, cross-reference resolution,
106
and integration with Sphinx's build system and extensions.
107
"""
108
109
def __init__(self, document) -> None:
110
"""
111
Initialize Sphinx renderer.
112
113
Args:
114
document: Sphinx document node to populate
115
"""
116
117
def resolve_reference(self, target: str, reftype: str = None) -> tuple[str, str] | None:
118
"""
119
Resolve Sphinx cross-reference.
120
121
Args:
122
target: Reference target
123
reftype: Type of reference (optional)
124
125
Returns:
126
Tuple of (title, uri) if resolved, None otherwise
127
"""
128
129
def handle_cross_reference(self, token, env) -> None:
130
"""
131
Handle cross-reference tokens for Sphinx.
132
133
Args:
134
token: Cross-reference token
135
env: Markdown-it environment
136
"""
137
```
138
139
Usage example:
140
141
```python
142
from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer
143
from myst_parser.parsers.mdit import create_md_parser
144
145
# In Sphinx environment
146
def process_myst_document(app, source_path, content):
147
# Create Sphinx document
148
document = app.env.new_document(source_path)
149
150
# Create Sphinx renderer
151
renderer = SphinxRenderer(document)
152
153
# Create parser with Sphinx configuration
154
config = create_myst_config(app)
155
md_parser = create_md_parser(config, renderer)
156
157
# Parse with Sphinx-specific handling
158
md_parser.render(content)
159
160
return document
161
```
162
163
### Document Factory
164
165
Utility functions for creating and configuring docutils documents with proper settings and metadata.
166
167
```python { .api }
168
def make_document(source_path: str, parser_cls=None):
169
"""
170
Create new docutils document with proper configuration.
171
172
Args:
173
source_path: Path to source file (for error reporting)
174
parser_cls: Optional parser class for settings
175
176
Returns:
177
Configured docutils document instance
178
"""
179
180
def token_line(token, default: int | None = None) -> int | None:
181
"""
182
Retrieve initial line number of markdown-it token.
183
184
Args:
185
token: Markdown-it token
186
default: Default line number if not found
187
188
Returns:
189
Line number or default value
190
"""
191
```
192
193
Usage example:
194
195
```python
196
from myst_parser.mdit_to_docutils.base import make_document, token_line
197
198
# Create document for parsing
199
document = make_document("example.md")
200
print(document.settings.env)
201
202
# Extract line numbers from tokens
203
def process_tokens(tokens):
204
for token in tokens:
205
line_num = token_line(token, default=1)
206
print(f"Token {token.type} at line {line_num}")
207
```
208
209
### HTML Processing
210
211
Advanced HTML-to-docutils conversion system for handling embedded HTML content within MyST documents.
212
213
```python { .api }
214
def html_to_nodes(
215
text: str,
216
line_number: int,
217
renderer: DocutilsRenderer
218
) -> list[nodes.Element]:
219
"""
220
Convert HTML to docutils nodes.
221
222
Handles HTML content within MyST documents, supporting HTML images
223
and admonitions based on enabled extensions.
224
225
Args:
226
text: HTML content to convert
227
line_number: Source line number for error reporting
228
renderer: DocutilsRenderer instance for context
229
230
Returns:
231
List of docutils nodes
232
"""
233
```
234
235
Usage example:
236
237
```python
238
from myst_parser.mdit_to_docutils.html_to_nodes import html_to_nodes
239
240
# Convert HTML to docutils nodes
241
html_content = """
242
<div class="custom-container">
243
<p>HTML content with <em>emphasis</em></p>
244
<ul>
245
<li>List item 1</li>
246
<li>List item 2</li>
247
</ul>
248
</div>
249
"""
250
251
# Convert HTML to nodes
252
nodes = html_to_nodes(
253
html_content,
254
line_number=10,
255
renderer=renderer
256
)
257
258
# Add nodes to document
259
document.extend(nodes)
260
```
261
262
### Post-Processing
263
264
MyST-Parser integrates with docutils' standard transform system for post-processing rendered documents. Standard docutils transforms handle footnotes, references, and other document-level operations automatically.
265
266
## Regular Expressions and Constants
267
268
Core regular expressions used in rendering:
269
270
```python { .api }
271
# URI and link processing
272
REGEX_SCHEME: Pattern = re.compile(r'^([a-zA-Z][a-zA-Z0-9+.-]*):')
273
REGEX_URI_TEMPLATE: Pattern = re.compile(r'\{[a-zA-Z_][a-zA-Z0-9_-]*\}')
274
275
# Directive processing
276
REGEX_DIRECTIVE_START: Pattern = re.compile(r'^[\s]{0,3}([`]{3,10}|[~]{3,10}|[:]{3,10})\{')
277
```
278
279
## Types
280
281
Document rendering related type definitions:
282
283
```python { .api }
284
class DocutilsRenderer:
285
"""Main renderer for markdown-it to docutils conversion."""
286
287
class SphinxRenderer(DocutilsRenderer):
288
"""Sphinx-specific renderer with additional functionality."""
289
290
# Type aliases from docutils
291
nodes.Element # Base docutils node type
292
nodes.document # Document root node
293
```