0
# Document Elements
1

2
Complete set of Pandoc AST element classes for building and manipulating documents. These classes represent all the structural and content elements that can appear in Pandoc documents, organized in a hierarchy that mirrors Pandoc's internal representation.
3

4
## Capabilities
5

6
### Document Container
7

8
Root document class that contains all content and metadata.
9

10
```python { .api }
11
class Doc(Element):
12
    """
13
    Pandoc document container with metadata and content blocks.
14

15
    Parameters:
16
    - *args: Block elements contained in the document
17
    - metadata: document metadata (dict)
18
    - format: output format such as 'html', 'latex', 'markdown'
19
    - api_version: Pandoc API version tuple (default: (1, 23))
20

21
    Properties:
22
    - content: ListContainer of Block elements
23
    - metadata: MetaMap of document metadata
24
    - format: str, output format
25
    - api_version: tuple, Pandoc API version
26
    - pandoc_version: tuple, runtime Pandoc version
27
    - pandoc_reader_options: dict, Pandoc reader options
28

29
    Methods:
30
    - get_metadata(key='', default=None, builtin=True): retrieve nested metadata
31
    """
32

33
    def __init__(self, *args, metadata={}, format='html', api_version=(1, 23)): ...
34
    def get_metadata(self, key='', default=None, builtin=True): ...
35
```
36

37
### Block Elements
38

39
Block-level elements that form the main document structure.
40

41
#### Text Blocks
42

43
```python { .api }
44
class Plain(Block):
45
    """Plain text block without paragraph formatting."""
46
    def __init__(self, *args): ...
47

48
class Para(Block):
49
    """Paragraph block containing inline elements."""
50
    def __init__(self, *args): ...
51

52
class BlockQuote(Block):
53
    """Block quotation containing other blocks."""
54
    def __init__(self, *args): ...
55

56
class Header(Block):
57
    """
58
    Section header with level and inline content.
59

60
    Parameters:
61
    - *args: Inline elements for header text
62
    - level: header level (1-6, default: 1)
63
    - identifier: element ID string
64
    - classes: list of CSS class names
65
    - attributes: dict of additional attributes
66
    """
67
    def __init__(self, *args, level=1, identifier='', classes=[], attributes={}): ...
68

69
class Div(Block):
70
    """
71
    Generic block container with attributes.
72

73
    Parameters:
74
    - *args: Block elements contained in the div
75
    - identifier: element ID string
76
    - classes: list of CSS class names
77
    - attributes: dict of additional attributes
78
    """
79
    def __init__(self, *args, identifier='', classes=[], attributes={}): ...
80
```
81

82
#### Code Blocks
83

84
```python { .api }
85
class CodeBlock(Block):
86
    """
87
    Code block with syntax highlighting support.
88

89
    Parameters:
90
    - text: code content string
91
    - identifier: element ID string
92
    - classes: list of language/class names for highlighting
93
    - attributes: dict of additional attributes
94
    """
95
    def __init__(self, text, identifier='', classes=[], attributes={}): ...
96

97
class RawBlock(Block):
98
    """
99
    Raw content block for specific output formats.
100

101
    Parameters:
102
    - text: raw content string
103
    - format: target format (e.g., 'html', 'latex', 'tex')
104
    """
105
    def __init__(self, text, format): ...
106
```
107

108
#### List Elements
109

110
```python { .api }
111
class BulletList(Block):
112
    """Unordered list containing ListItem elements."""
113
    def __init__(self, *args): ...
114

115
class OrderedList(Block):
116
    """
117
    Ordered list with numbering style.
118

119
    Parameters:
120
    - *args: ListItem elements
121
    - start: starting number (default: 1)
122
    - style: numbering style ('Decimal', 'LowerRoman', 'UpperRoman', 'LowerAlpha', 'UpperAlpha')
123
    - delimiter: delimiter style ('Period', 'OneParen', 'TwoParens')
124
    """
125
    def __init__(self, *args, start=1, style='Decimal', delimiter='Period'): ...
126

127
class DefinitionList(Block):
128
    """Definition list containing DefinitionItem elements."""
129
    def __init__(self, *args): ...
130

131
class LineBlock(Block):
132
    """Line block preserving line breaks."""
133
    def __init__(self, *args): ...
134
```
135

136
#### Other Blocks
137

138
```python { .api }
139
class HorizontalRule(Block):
140
    """Horizontal rule/separator."""
141
    def __init__(self): ...
142

143
class Figure(Block):
144
    """
145
    Figure block (Pandoc 3.0+).
146

147
    Parameters:
148
    - *args: Block elements in figure body
149
    - caption: Caption element (optional)
150
    - identifier: element ID string
151
    - classes: list of CSS class names
152
    - attributes: dict of additional attributes
153
    """
154
    def __init__(self, *args, caption=None, identifier='', classes=[], attributes={}): ...
155

156
class Null(Block):
157
    """Null block (deprecated in Pandoc 3.0+)."""
158
    def __init__(self): ...
159
```
160

161
### Inline Elements
162

163
Inline elements that appear within block elements.
164

165
#### Text Elements
166

167
```python { .api }
168
class Str(Inline):
169
    """
170
    String of text.
171

172
    Parameters:
173
    - text: text content string
174
    """
175
    def __init__(self, text): ...
176

177
class Space(Inline):
178
    """Inter-word space."""
179
    def __init__(self): ...
180

181
class SoftBreak(Inline):
182
    """Soft line break (converted to space in most formats)."""
183
    def __init__(self): ...
184

185
class LineBreak(Inline):
186
    """Hard line break."""
187
    def __init__(self): ...
188
```
189

190
#### Formatting Elements
191

192
```python { .api }
193
class Emph(Inline):
194
    """Emphasis/italic text containing inline elements."""
195
    def __init__(self, *args): ...
196

197
class Strong(Inline):
198
    """Strong/bold text containing inline elements."""
199
    def __init__(self, *args): ...
200

201
class Underline(Inline):
202
    """Underlined text containing inline elements."""
203
    def __init__(self, *args): ...
204

205
class Strikeout(Inline):
206
    """Strikethrough text containing inline elements."""
207
    def __init__(self, *args): ...
208

209
class Superscript(Inline):
210
    """Superscript text containing inline elements."""
211
    def __init__(self, *args): ...
212

213
class Subscript(Inline):
214
    """Subscript text containing inline elements."""
215
    def __init__(self, *args): ...
216

217
class SmallCaps(Inline):
218
    """Small capitals text containing inline elements."""
219
    def __init__(self, *args): ...
220

221
class Span(Inline):
222
    """
223
    Generic inline container with attributes.
224

225
    Parameters:
226
    - *args: Inline elements contained in the span
227
    - identifier: element ID string
228
    - classes: list of CSS class names
229
    - attributes: dict of additional attributes
230
    """
231
    def __init__(self, *args, identifier='', classes=[], attributes={}): ...
232
```
233

234
#### Code and Math Elements
235

236
```python { .api }
237
class Code(Inline):
238
    """
239
    Inline code.
240

241
    Parameters:
242
    - text: code content string
243
    - identifier: element ID string
244
    - classes: list of language/class names
245
    - attributes: dict of additional attributes
246
    """
247
    def __init__(self, text, identifier='', classes=[], attributes={}): ...
248

249
class Math(Inline):
250
    """
251
    Mathematical expression.
252

253
    Parameters:
254
    - text: LaTeX math expression string
255
    - format: math format ('InlineMath' or 'DisplayMath')
256
    """
257
    def __init__(self, text, format='InlineMath'): ...
258

259
class RawInline(Inline):
260
    """
261
    Raw inline content for specific formats.
262

263
    Parameters:
264
    - text: raw content string
265
    - format: target format (e.g., 'html', 'latex', 'tex')
266
    """
267
    def __init__(self, text, format): ...
268
```
269

270
#### Links and Media
271

272
```python { .api }
273
class Link(Inline):
274
    """
275
    Hyperlink element.
276

277
    Parameters:
278
    - *args: Inline elements for link text
279
    - url: link URL string
280
    - title: link title string (tooltip)
281
    - identifier: element ID string
282
    - classes: list of CSS class names
283
    - attributes: dict of additional attributes
284
    """
285
    def __init__(self, *args, url='', title='', identifier='', classes=[], attributes={}): ...
286

287
class Image(Inline):
288
    """
289
    Image element.
290

291
    Parameters:
292
    - *args: Inline elements for alt text
293
    - url: image URL string
294
    - title: image title string
295
    - identifier: element ID string
296
    - classes: list of CSS class names
297
    - attributes: dict of additional attributes
298
    """
299
    def __init__(self, *args, url='', title='', identifier='', classes=[], attributes={}): ...
300
```
301

302
#### Other Inline Elements
303

304
```python { .api }
305
class Note(Inline):
306
    """Footnote containing block elements."""
307
    def __init__(self, *args): ...
308

309
class Quoted(Inline):
310
    """
311
    Quoted text with quote type.
312

313
    Parameters:
314
    - *args: Inline elements for quoted content
315
    - quote_type: quote style ('SingleQuote' or 'DoubleQuote')
316
    """
317
    def __init__(self, *args, quote_type='DoubleQuote'): ...
318

319
class Cite(Inline):
320
    """
321
    Citation with citation objects.
322

323
    Parameters:
324
    - *args: Inline elements for citation text
325
    - citations: list of Citation objects
326
    """
327
    def __init__(self, *args, citations=[]): ...
328
```
329

330
### Table Elements
331

332
Elements for creating and structuring tables with headers, bodies, rows, and cells.
333

334
```python { .api }
335
class Table(Block):
336
    """
337
    Table container with header, body, footer, and metadata.
338

339
    Parameters:
340
    - *args: TableBody elements
341
    - head: TableHead element (optional)
342
    - foot: TableFoot element (optional)
343
    - caption: Caption element (optional)
344
    - colspec: list of (alignment, width) tuples for columns
345
    """
346
    def __init__(self, *args, head=None, foot=None, caption=None, colspec=[]): ...
347

348
class TableHead(Block):
349
    """Table header section containing TableRow elements."""
350
    def __init__(self, *args): ...
351

352
class TableFoot(Block):
353
    """Table footer section containing TableRow elements."""
354
    def __init__(self, *args): ...
355

356
class TableBody(Block):
357
    """Table body section containing TableRow elements."""
358
    def __init__(self, *args): ...
359

360
class TableRow(Element):
361
    """Table row containing TableCell elements."""
362
    def __init__(self, *args): ...
363

364
class TableCell(Element):
365
    """
366
    Individual table cell containing block elements.
367

368
    Parameters:
369
    - *args: Block elements in the cell
370
    - alignment: cell alignment ('AlignLeft', 'AlignRight', 'AlignCenter', 'AlignDefault')
371
    - rowspan: number of rows the cell spans (default: 1)
372
    - colspan: number of columns the cell spans (default: 1)
373
    """
374
    def __init__(self, *args, alignment='AlignDefault', rowspan=1, colspan=1): ...
375

376
class Caption(Element):
377
    """Table caption containing block elements."""
378
    def __init__(self, *args): ...
379
```
380

381
### List Components
382

383
Elements that form parts of list structures.
384

385
```python { .api }
386
class ListItem(Element):
387
    """Individual list item containing block elements."""
388
    def __init__(self, *args): ...
389

390
class Definition(Element):
391
    """Definition in definition list containing block elements."""
392
    def __init__(self, *args): ...
393

394
class DefinitionItem(Element):
395
    """
396
    Term-definition pair in definition list.
397

398
    Parameters:
399
    - term: list of Inline elements for the term
400
    - definitions: list of Definition elements
401
    """
402
    def __init__(self, term, definitions): ...
403

404
class LineItem(Element):
405
    """Line in line block containing inline elements."""
406
    def __init__(self, *args): ...
407
```
408

409
### Citation Elements
410

411
```python { .api }
412
class Citation(Element):
413
    """
414
    Citation reference for academic citations.
415

416
    Parameters:
417
    - id: citation identifier string
418
    - mode: citation mode ('NormalCitation', 'AuthorInText', 'SuppressAuthor')
419
    - prefix: list of Inline elements before citation
420
    - suffix: list of Inline elements after citation
421
    - note_num: note number (int)
422
    - hash: citation hash (int)
423
    """
424
    def __init__(self, id, mode='NormalCitation', prefix=[], suffix=[], note_num=0, hash=0): ...
425
```
426

427
### Metadata Elements
428

429
Elements for document frontmatter metadata.
430

431
```python { .api }
432
class MetaList(MetaValue):
433
    """List of metadata values."""
434
    def __init__(self, *args): ...
435

436
class MetaMap(MetaValue):
437
    """Map/dictionary of metadata key-value pairs."""
438
    def __init__(self, *args, **kwargs): ...
439

440
class MetaInlines(MetaValue):
441
    """Inline content as metadata."""
442
    def __init__(self, *args): ...
443

444
class MetaBlocks(MetaValue):
445
    """Block content as metadata."""
446
    def __init__(self, *args): ...
447

448
class MetaString(MetaValue):
449
    """String metadata value."""
450
    def __init__(self, text): ...
451

452
class MetaBool(MetaValue):
453
    """Boolean metadata value."""
454
    def __init__(self, boolean): ...
455
```
456

457
## Usage Examples
458

459
### Building Documents Programmatically
460

461
```python
462
import panflute as pf
463

464
# Create a complex document structure
465
doc = pf.Doc(
466
    # Title and metadata
467
    pf.Header(pf.Str('My Research Paper'), level=1),
468
    
469
    # Abstract
470
    pf.Header(pf.Str('Abstract'), level=2),
471
    pf.Para(
472
        pf.Str('This paper discusses '),
473
        pf.Emph(pf.Str('important findings')),
474
        pf.Str(' in the field of computational linguistics.')
475
    ),
476
    
477
    # Introduction with citation
478
    pf.Header(pf.Str('Introduction'), level=2),
479
    pf.Para(
480
        pf.Str('Previous work by '),
481
        pf.Cite(
482
            pf.Str('Smith et al.'),
483
            citations=[pf.Citation('smith2020', mode='NormalCitation')]
484
        ),
485
        pf.Str(' has shown that...')
486
    ),
487
    
488
    # Code example
489
    pf.Header(pf.Str('Implementation'), level=2),
490
    pf.Para(pf.Str('The following code demonstrates our approach:')),
491
    pf.CodeBlock(
492
        'def process_text(text):\n    return text.upper()',
493
        classes=['python']
494
    ),
495
    
496
    # Results table
497
    pf.Header(pf.Str('Results'), level=2),
498
    pf.Table(
499
        pf.TableBody(
500
            pf.TableRow(
501
                pf.TableCell(pf.Plain(pf.Str('Metric'))),
502
                pf.TableCell(pf.Plain(pf.Str('Before'))),
503
                pf.TableCell(pf.Plain(pf.Str('After')))
504
            ),
505
            pf.TableRow(
506
                pf.TableCell(pf.Plain(pf.Str('Accuracy'))),
507
                pf.TableCell(pf.Plain(pf.Str('85%'))),
508
                pf.TableCell(pf.Plain(pf.Str('100%')))
509
            ),
510
            pf.TableRow(
511
                pf.TableCell(pf.Plain(pf.Str('Speed'))),
512
                pf.TableCell(pf.Plain(pf.Str('100ms'))),
513
                pf.TableCell(pf.Plain(pf.Str('70ms')))
514
            )
515
        ),
516
        caption=pf.Caption(pf.Plain(pf.Str('Performance Comparison')))
517
    ),
518
    
519
    # List of results
520
    pf.Header(pf.Str('Additional Results'), level=2),
521
    pf.BulletList(
522
        pf.ListItem(pf.Plain(pf.Str('Accuracy improved by 15%'))),
523
        pf.ListItem(pf.Plain(pf.Str('Processing time reduced by 30%'))),
524
        pf.ListItem(pf.Plain(pf.Str('Memory usage optimized')))
525
    ),
526
    
527
    # Metadata
528
    metadata={
529
        'author': pf.MetaString('Dr. Jane Researcher'),
530
        'date': pf.MetaString('2024-01-15'),
531
        'keywords': pf.MetaList(
532
            pf.MetaString('NLP'),
533
            pf.MetaString('machine learning'),
534
            pf.MetaString('text processing')
535
        )
536
    }
537
)
538
```
539

540
### Element Traversal and Modification
541

542
```python
543
import panflute as pf
544

545
def enhance_links(elem, doc):
546
    """Add target="_blank" to external links."""
547
    if isinstance(elem, pf.Link):
548
        if elem.url.startswith('http'):
549
            elem.attributes['target'] = '_blank'
550
            elem.attributes['rel'] = 'noopener noreferrer'
551
    return elem
552

553
def collect_headers(elem, doc):
554
    """Collect all headers for table of contents."""
555
    if isinstance(elem, pf.Header):
556
        if not hasattr(doc, 'headers'):
557
            doc.headers = []
558
        doc.headers.append({
559
            'level': elem.level,
560
            'text': pf.stringify(elem),
561
            'identifier': elem.identifier
562
        })
563

564
# Process a document
565
if __name__ == '__main__':
566
    pf.run_filters([enhance_links, collect_headers])
567
```