0
# Markdown Processing
1

2
Markdown extension and processors for parsing and rendering `::: identifier` autodoc blocks within Markdown documents. The processing system integrates with Python-Markdown to provide seamless documentation extraction during Markdown conversion.
3

4
## Capabilities
5

6
### Markdown Extension
7

8
Primary Markdown extension that integrates mkdocstrings processing into the Markdown conversion pipeline.
9

10
```python { .api }
11
class MkdocstringsExtension(Extension):
12
    """Main Markdown extension for mkdocstrings."""
13
    
14
    def __init__(self, handlers: Handlers, autorefs: AutorefsPlugin, **kwargs: Any) -> None:
15
        """
16
        Initialize the extension.
17
        
18
        Args:
19
            handlers: Handlers instance for processing
20
            autorefs: AutorefsPlugin instance for cross-references
21
            **kwargs: Additional extension arguments
22
        """
23
    
24
    def extendMarkdown(self, md: Markdown) -> None:
25
        """
26
        Register processors with Markdown instance.
27
        
28
        Args:
29
            md: Markdown instance to extend
30
        """
31
```
32

33
**Usage Example:**
34

35
```python
36
from markdown import Markdown
37
from mkdocstrings import MkdocstringsExtension, Handlers
38

39
# Create handlers
40
handlers = Handlers(
41
    theme="material",
42
    default="python",
43
    inventory_project="my-project"
44
)
45

46
# Create extension
47
extension = MkdocstringsExtension(handlers=handlers, autorefs=None)
48

49
# Add to Markdown
50
md = Markdown(extensions=[extension])
51

52
# Process markdown with autodoc blocks
53
markdown_text = """
54
# My Documentation
55

56
::: my_module.MyClass
57
    options:
58
      show_source: false
59
      
60
::: my_module.my_function
61
"""
62

63
html_output = md.convert(markdown_text)
64
```
65

66
### AutoDoc Block Processor
67

68
Block processor that identifies and processes `::: identifier` autodoc blocks in Markdown content.
69

70
```python { .api }
71
class AutoDocProcessor(BlockProcessor):
72
    """Our 'autodoc' Markdown block processor."""
73
    
74
    regex: re.Pattern = re.compile(r"^(?P<heading>#{1,6} *|)::: ?(?P<name>.+?) *$", flags=re.MULTILINE)
75
    """The regular expression to match our autodoc instructions."""
76
    
77
    def __init__(self, md: Markdown, *, handlers: Handlers, autorefs: AutorefsPlugin) -> None:
78
        """
79
        Initialize the object.
80
        
81
        Args:
82
            md: A markdown.Markdown instance
83
            handlers: The handlers container
84
            autorefs: The autorefs plugin instance
85
        """
86
    
87
    def test(self, parent: Element, block: str) -> bool:
88
        """
89
        Match our autodoc instructions.
90
        
91
        Args:
92
            parent: The parent element in the XML tree
93
            block: The block to be tested
94
            
95
        Returns:
96
            Whether this block should be processed or not
97
        """
98
    
99
    def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
100
        """
101
        Run code on the matched blocks.
102
        
103
        Args:
104
            parent: The parent element in the XML tree
105
            blocks: The matched blocks
106
        """
107
```
108

109
**AutoDoc Block Format:**
110

111
The processor recognizes blocks with this syntax:
112

113
```markdown
114
::: identifier
115
    options:
116
      option1: value1
117
      option2: value2
118
    selection:
119
      members:
120
        - member1
121
        - member2
122
    rendering:
123
      show_source: false
124
      heading_level: 2
125
```
126

127
**Usage Examples:**
128

129
Basic usage:
130
```markdown
131
::: my_module.MyClass
132
```
133

134
With options:
135
```markdown
136
::: my_module.MyClass
137
    options:
138
      show_source: false
139
      docstring_style: google
140
```
141

142
With member selection:
143
```markdown
144
::: my_module
145
    selection:
146
      members:
147
        - MyClass
148
        - my_function
149
      filters:
150
        - "!^_"  # Exclude private members
151
```
152

153
### Inner Extension
154

155
Extension for processing Markdown sub-documents within handlers, enabling nested Markdown processing.
156

157
```python { .api }
158
class MkdocstringsInnerExtension(Extension):
159
    """Extension for Markdown sub-documents processed by handlers."""
160
    
161
    def __init__(self, headings: list[Element]) -> None:
162
        """
163
        Initialize with heading elements.
164
        
165
        Args:
166
            headings: List of heading elements to track
167
        """
168
    
169
    def extendMarkdown(self, md: Markdown) -> None:
170
        """
171
        Configure Markdown for inner processing.
172
        
173
        Args:
174
            md: Markdown instance to configure
175
        """
176
```
177

178
**Usage in Handlers:**
179

180
```python
181
def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -> str:
182
    # Create inner extension for nested Markdown
183
    headings = []
184
    inner_extension = MkdocstringsInnerExtension(headings)
185
    
186
    # Process docstring Markdown
187
    inner_md = Markdown(extensions=[inner_extension])
188
    docstring_html = inner_md.convert(data.docstring)
189
    
190
    # Use in template
191
    return template.render(
192
        data=data,
193
        docstring_html=docstring_html,
194
        headings=headings
195
    )
196
```
197

198
## Processing Workflow
199

200
### Block Recognition
201

202
The AutoDoc processor uses regex patterns to identify autodoc blocks:
203

204
1. **Pattern Matching**: Blocks starting with `:::` followed by an identifier
205
2. **Option Parsing**: YAML-style options blocks beneath the identifier
206
3. **Multi-line Support**: Blocks can span multiple lines with proper indentation
207

208
### Block Processing
209

210
When an autodoc block is found:
211

212
1. **Parse Identifier**: Extract the object identifier to document
213
2. **Parse Options**: Parse YAML options and merge with defaults
214
3. **Handler Selection**: Determine which handler to use (from options or default)
215
4. **Data Collection**: Handler collects documentation data from source
216
5. **Rendering**: Handler renders data into HTML
217
6. **Integration**: HTML is inserted into the Markdown document tree
218

219
### Error Handling
220

221
The processing system handles various error conditions:
222

223
```python
224
try:
225
    # Collect documentation data
226
    data = handler.collect(identifier, options)
227
    
228
    # Render to HTML
229
    html = handler.render(data, options)
230
    
231
except CollectionError as e:
232
    # Log collection failure and continue
233
    logger.error(f"Collection failed for {identifier}: {e}")
234
    html = f"<div class='error'>Failed to collect {identifier}</div>"
235
    
236
except Exception as e:
237
    # Log unexpected errors
238
    logger.exception(f"Unexpected error processing {identifier}")
239
    html = f"<div class='error'>Error processing {identifier}</div>"
240
```
241

242
## Advanced Processing Features
243

244
### Option Inheritance
245

246
Options can be specified at multiple levels:
247

248
1. **Global Handler Options**: Set in plugin configuration
249
2. **Local Block Options**: Set in individual autodoc blocks
250
3. **Option Merging**: Local options override global options
251

252
```yaml
253
# Global options in mkdocs.yml
254
plugins:
255
  - mkdocstrings:
256
      handlers:
257
        python:
258
          options:
259
            show_source: false
260
            docstring_style: google
261
```
262

263
```markdown
264
<!-- Local options override global -->
265
::: my_module.MyClass
266
    options:
267
      show_source: true  # Overrides global setting
268
```
269

270
### Selection Filters
271

272
Control which members are documented:
273

274
```markdown
275
::: my_module
276
    selection:
277
      members:
278
        - MyClass
279
        - my_function
280
      filters:
281
        - "!^_"      # Exclude private members
282
        - "!^test_"  # Exclude test functions
283
      inherited_members: true
284
      docstring_sections:
285
        - attributes
286
        - parameters
287
        - returns
288
```
289

290
### Rendering Control
291

292
Control how documentation is rendered:
293

294
```markdown
295
::: my_module.MyClass
296
    rendering:
297
      show_source: false
298
      show_root_heading: true
299
      show_root_toc_entry: false
300
      heading_level: 2
301
      show_category_heading: true
302
      members_order: alphabetical
303
```
304

305
### Cross-Reference Integration
306

307
Integration with autorefs for cross-referencing:
308

309
```python
310
# In handler render method
311
def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -> str:
312
    # Register cross-references
313
    if self.autorefs:
314
        self.autorefs.register_anchor(data.name, data.url)
315
    
316
    # Render with cross-reference support
317
    return template.render(data=data, autorefs=self.autorefs)
318
```
319

320
This enables automatic linking between documentation sections and external references.