### Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/api.md

Represents an example.

```APIDOC
## Example

### Description
Represents an example.

### Signature
```skip
Example()
```
```

--------------------------------

### For Loop Examples

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Shows how to use 'for' loops to iterate over arrays or maps, with examples of accessing elements and using separators.

```text
$for(foo)$$foo$$sep$, $endfor$

$for(foo)$
  - $foo.last$, $foo.first$
$endfor$

${ for(foo.bar) }
  - ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }

$for(mymap)$
$it.name$: $it.office$
$endfor$
```

```text
${ for(foo) }${ foo }${ sep }, ${ endfor }
```

```text
${ for(foo.bar) }
  - ${ it.last }, ${ it.first }
${ endfor }
```

--------------------------------

### Numbered Example List

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Shows the `example_lists` extension for creating numbered examples using the `(@)` syntax, with automatic numbering.

```pandoc
>>> """
... (@)  My first example will be numbered (1).
... (@)  My second example will be numbered (2).
... 
... Explanation of examples.
... 
... (@)  My third example will be numbered (3).
... """
... # doctest: +PANDOC
Pandoc(Meta(map()), [OrderedList((1, Example(), TwoParens()), [[Plain([Str(u
    'My'), Space(), Str(u'first'), Space(), Str(u'example'), Space(), Str(u'will
    '), Space(), Str(u'be'), Space(), Str(u'numbered'), Space(), Str(u'(1).')])] 
    , [Plain([Str(u'My'), Space(), Str(u'second'), Space(), Str(u'example'), Spa
    ce(), Str(u'will'), Space(), Str(u'be'), Space(), Str(u'numbered'), Space(),
     Str(u'(2).')])]]), Para([Str(u'Explanation'), Space(), Str(u'of'), Space(),
     Str(u'examples.')]), OrderedList((3, Example(), TwoParens()), [[Plain([Str( 
    u'My'), Space(), Str(u'third'), Space(), Str(u'example'), Space(), Str(u'wil
    l'), Space(), Str(u'be'), Space(), Str(u'numbered'), Space(), Str(u'(3).')])
    ]])])
```

--------------------------------

### Initialism as Paragraph Start (Markdown)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Markdown example showing how to prevent an initialism followed by a period from being treated as a list item.

```markdown
B. Russell was an English philosopher.
```

--------------------------------

### Pandoc Example Lists Syntax

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Use the '@' marker for sequentially numbered examples. The numbering continues across lists. Labels can be used for references.

```markdown
(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).
```

```markdown
(@good)  This is a good example.

As (@good) illustrates, ...
```

--------------------------------

### Install Pandoc Binary and Python Library

Source: https://context7.com/boisgera/pandoc/llms.txt

Install the Pandoc binary using a package manager like conda, followed by the Python library using pip.

```bash
conda install -c conda-forge pandoc
```

```bash
pip install --upgrade pandoc
```

--------------------------------

### GladTeX Processing Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Illustrates the command-line usage for processing TeX math with GladTeX to generate SVG images and HTML.

```bash
pandoc -s --gladtex input.md -o myfile.htex
gladtex -d image_dir myfile.htex
# produces myfile.html and images in image_dir
```

--------------------------------

### Pandoc Defaults File Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

A sample YAML file demonstrating the structure and fields for Pandoc's default options.

```yaml
from: markdown+emoji
# reader: may be used instead of from:
to: html5
# writer: may be used instead of to:

# leave blank for output to stdout:
output-file:
# leave blank for input from stdin, use [] for no input:
input-files:
- preface.md
- content.md
# or you may use input-file: with a single value

# Include options from the specified defaults files.
# The files will be searched for first in the working directory
# and then in the defaults subdirectory of the user data directory.
```

--------------------------------

### Labeled Examples in Pandoc AST

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

The Python representation of labeled examples and their references.

```python
Pandoc(Meta({}), [OrderedList((1, Example(), TwoParens()), [[Plain([Str('This'), Space(), Str('is'), Space(), Str('a'), Space(), Str('good'), Space(), Str('example.')])]]), Para([Str('As'), Space(), Str('(1)'), Space(), Str('illustrates,'), Space(), Str('…')])])
```

--------------------------------

### Sequential Numbered Examples in Pandoc AST

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

The Python representation of sequentially numbered examples using '@' markers.

```python
Pandoc(Meta({}), [OrderedList((1, Example(), TwoParens()), [[Plain([Str('My'), Space(), Str('first'), Space(), Str('example'), Space(), Str('will'), Space(), Str('be'), Space(), Str('numbered'), Space(), Str('(1).')])], [Plain([Str('My'), Space(), Str('second'), Space(), Str('example'), Space(), Str('will'), Space(), Str('be'), Space(), Str('numbered'), Space(), Str('(2).')])]]), Para([Str('Explanation'), Space(), Str('of'), Space(), Str('examples.')]), OrderedList((3, Example(), TwoParens()), [[Plain([Str('My'), Space(), Str('third'), Space(), Str('example'), Space(), Str('will'), Space(), Str('be'), Space(), Str('numbered'), Space(), Str('(3).')])]])])
```

--------------------------------

### Partial Inclusion Examples

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Demonstrates how to include other template files (partials) using directives, including applying them to variables and specifying separators.

```text
${ styles() }

${ styles.html() }
```

```text
${ date:fancy() }

${ articles:bibentry() }
```

```text
${months[, ]}$

${articles:bibentry()[; ]$
```

--------------------------------

### Conditional Logic Examples

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Illustrates the use of 'if', 'else', and 'elseif' directives for conditional rendering of template content.

```text
$if(foo)$bar$endif$

$if(foo)$
  $foo$
$endif$

$if(foo)$ 
part one
$else$
part two
$endif$

${if(foo)}bar${endif}

${if(foo)}
  ${foo}
${endif}

${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}
```

```text
$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
ZZZ
$endif$
```

--------------------------------

### Sequential Numbered Examples in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Use the '@' marker for sequentially numbered examples. Numbering continues across lists.

```markdown
(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).
```

--------------------------------

### Pandoc Defaults File Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

A simple defaults file can specify basic configuration options like verbosity.

```yaml
verbosity: INFO
```

--------------------------------

### Labeled Example List

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Demonstrates the `example_lists` extension with labels like `(@good)`, which are rendered as their corresponding number in the text.

```pandoc
>>> """
... (@good)  This is a good example.
... 
... As (@good) illustrates, ...
... """
... # doctest: +PANDOC
Pandoc(Meta(map()), [OrderedList((1, Example(), TwoParens()), [[Plain([Str(u
    'This'), Space(), Str(u'is'), Space(), Str(u'a'), Space(), Str(u'good'), Spa
    ce(), Str(u'example.')])]]), Para([Str(u'As'), Space(), Str(u'(1)'), Space()
    , Str(u'illustrates,'), Space(), Str(u'...')])])
```

--------------------------------

### Pandoc Command with Metadata File

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Example of how to use Pandoc with separate Markdown files and a YAML metadata file.

```bash
pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
```

--------------------------------

### Pandoc: Short Subscript and Superscript

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Example of MultiMarkdown style subscripts and superscripts, enabled by the `short_subsuperscript` extension. Subscripts start with '~' and superscripts with '^'.

```markdown
x^2 = 4

Oxygen is O~2.
```

--------------------------------

### Build Pandoc Types with Pixi

Source: https://github.com/boisgera/pandoc/blob/master/fetch-types/README.md

Run this command to generate an updated `pandoc-types.js` file. Ensure you have `pixi` installed.

```bash
$ pixi run build
```

--------------------------------

### Install Pandoc Python Library

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/cli.md

Install the latest version of the pandoc-python-library from GitHub using pip. This command ensures you have the most up-to-date development version.

```bash
$ pip install --upgrade git+https://github.com/boisgera/pandoc.git
```

--------------------------------

### Markdown Pipe Table Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Demonstrates the basic syntax for a pipe table in Markdown, including alignment indicators and a caption.

```markdown
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.
```

--------------------------------

### Install Pandoc Python Library with Pip

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/getting-started.md

Installs or upgrades the Pandoc Python library using pip, the standard package installer for Python.

```bash
$ pip install --upgrade pandoc
```

--------------------------------

### Example Pandoc Document Structure

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/cookbook.md

Illustrates the structure of a simple Pandoc document with basic text content.

```pycon
>>> HELLOWORLD_DOC
Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
```

--------------------------------

### Ordered List with Custom Start and Sublist (Markdown)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Demonstrates an ordered list starting at 9 with custom numbering and a sublist using lowercase roman numerals.

```markdown
9)  Ninth
10)  Tenth
11)  Eleventh
      i. subone
     ii. subtwo
    iii. subthree
```

--------------------------------

### Ordered List with Custom Start Numbering

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Demonstrates the `start_num` extension for ordered lists, allowing custom starting numbers and different list styles (Decimal, LowerRoman, LowerAlpha, etc.).

```pandoc
>>> """
...  9)  Ninth
...  10)  Tenth
...  11)  Eleventh
...         i. subone
...        ii. subtwo
...       iii. subthree
...  """
... # doctest: +PANDOC
Pandoc(Meta(map()), [OrderedList((9, Decimal(), OneParen()), [[Plain([Str(u'\nNinth')])], [Plain([Str(u'Tenth')])], [Plain([Str(u'Eleventh'), SoftBreak(),
     Str(u'i.'), Space(), Str(u'subone')]), OrderedList((2, LowerRoman(), Period
    ()), [[Plain([Str(u'subtwo')])], [Plain([Str(u'subthree')])]])]])])
```

```pandoc
>>> """
... (2) Two
... (5) Three
... 1.  Four
... *   Five
... """
... # doctest: +PANDOC
Pandoc(Meta(map()), [OrderedList((2, Decimal(), TwoParens()), [[Plain([Str(u
    'Two')])], [Plain([Str(u'Three')])]]), OrderedList((1, Decimal(), Period()),
     [[Plain([Str(u'Four')])]]), BulletList([[Plain([Str(u'Five')])]])])
```

--------------------------------

### Multi-line Title Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Demonstrates how to format a title that spans multiple lines. Continuation lines must begin with leading space.

```markdown
% My title
  on multiple lines
```

--------------------------------

### Check Pandoc Version

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Verifies that Pandoc version 1.16 is installed before running tests. Requires the `subprocess` module.

```python
from subprocess import Popen, PIPE
p = Popen(["pandoc", "-v"], stdout=PIPE)
if b"pandoc 1.16" not in p.communicate()[0]:
    raise RuntimeError("pandoc 1.16 not found")
```

--------------------------------

### Wrapper Script Argument Handling Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Demonstrates how --ignore-args can be used in wrapper scripts to exclude specific arguments from Pandoc processing.

```bash
pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
```

```bash
pandoc -o foo.html -s
```

--------------------------------

### Markdown Line Block Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Demonstrates the Markdown syntax for line blocks, preserving line breaks and leading spaces. Useful for verse and addresses.

```markdown
| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718
```

--------------------------------

### Ugly Pipe Table Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Illustrates a valid but less visually aligned pipe table in Markdown, demonstrating that column alignment in the source is not strictly necessary.

```markdown
fruit| price
-----|-----:
```

--------------------------------

### Markdown Examples of Header Identifiers

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Demonstrates assigning the identifier 'foo' to various heading types using Markdown syntax.

```markdown
# My heading {#foo}
        
        ## My heading ##    {#foo}
        
        My other heading   {#foo}
        ---------------
```

--------------------------------

### Find specific elements in HELLOWORLD_DOC

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/cookbook.md

Examples of using the find helper function to locate Meta, Para, and Str elements within the HELLOWORLD_DOC document.

```pycon
>>> find(HELLOWORLD_DOC, Meta)
Meta({})
>>> find(HELLOWORLD_DOC, Para)
Para([Str('Hello'), Space(), Str('world!')])
>>> find(HELLOWORLD_DOC, Str)
Str('Hello')
>>> find(HELLOWORLD_DOC, LineBreak)
```

--------------------------------

### Python AST for Markdown Definition List

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

The Python Abstract Syntax Tree (AST) representation for the Markdown definition list example.

```python
Pandoc(Meta({}), [DefinitionList([([Str('Term'), Space(), Str('1')], [[Para([Str('Definition'), Space(), Str('1')])]]), ([Str('Term'), Space(), Str('2'), Space(), Str('with'), Space(), Emph([Str('inline'), Space(), Str('markup')])], [[Para([Str('Definition'), Space(), Str('2')]), CodeBlock(('', [], []), '{ some code, part of Definition 2 }'), Para([Str('Third'), Space(), Str('paragraph'), Space(), Str('of'), Space(), Str('definition'), Space(), Str('2.')])]])])])
```

--------------------------------

### Fetch and Display README Content

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/cli.md

This example shows how to download the project's README.md file using `curl` and then display the first 10 lines using `head`. This is useful for quickly inspecting project details.

```bash
$ URL="https://raw.githubusercontent.com/boisgera/pandoc/master/README.md"
$ curl $URL --output README.md 
$ cat README.md | head -n 10

Pandoc (Python Library)
================================================================================

[![build](https://github.com/boisgera/pandoc/actions/workflows/build.yml/badge.svg)](https://github.com/boisgera/pandoc/actions/workflows/build.yml)
[![Downloads](https://pepy.tech/badge/pandoc)](https://pepy.tech/project/pandoc)
[![Gitter chat](https://badges.gitter.im/boisgera/python-pandoc.svg)](https://gitter.im/python-pandoc/community#)

*This README is about the 2.x branch of the library (alpha stage!). Only the 1.x branch is available on PyPi at the moment.*
```

--------------------------------

### Line Block Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Line blocks preserve line breaks and leading whitespace. Lines start with a vertical bar and a space. Continuation lines must also begin with a space.

```text
| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical
```

```text
| 200 Main St.
| Berkeley, CA 94718
```

```text
| The Right Honorable Most Venerable and Righteous Samuel L.
  Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718
```

--------------------------------

### Printing a Default Custom Writer Lua File

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Command to print the default sample Lua script for custom writers, which can be used as a starting point for modifications.

```bash
pandoc --print-default-data-file sample.lua
```

--------------------------------

### Iterate with Path to Get Full Path Indices

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/iteration.md

Iterating with `path=True` allows access to all ancestor elements. This example demonstrates constructing a string representation of the full path indices to locate an element relative to the root.

```pycon
>>> for elt, path in pandoc.iter(doc, path=True):
...     indices = [i for holder, i in path]
...     z = "".join(f"[{i}]" for i in indices)
...     print(f"doc{z} == {elt!r}")
doc == Pandoc(Meta({}), [Header(1, ('title', [], []), [Str('Title')]), Para([Str('Content')])])
doc[0] == Meta({})
doc[0][0] == {}
doc[1] == [Header(1, ('title', [], []), [Str('Title')]), Para([Str('Content')])]
doc[1][0] == Header(1, ('title', [], []), [Str('Title')])
doc[1][0][0] == 1
doc[1][0][1] == ('title', [], [])
doc[1][0][1][0] == 'title'
doc[1][0][1][1] == []
doc[1][0][1][2] == []
doc[1][0][2] == [Str('Title')]
doc[1][0][2][0] == Str('Title')
doc[1][0][2][0][0] == 'Title'
doc[1][1] == Para([Str('Content')])
doc[1][1][0] == [Str('Content')]
doc[1][1][0][0] == Str('Content')
doc[1][1][0][0][0] == 'Content'
```

--------------------------------

### Import Pandoc Types

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/document.md

Import all types from the pandoc.types module. This is a common starting point for interacting with Pandoc's type system.

```pycon
>>> from pandoc.types import *
```

--------------------------------

### Simple Table AST in Python

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Shows the Pandoc Abstract Syntax Tree (AST) representation of a simple table in Python, corresponding to the Markdown example.

```python
Pandoc(Meta({}), [Table(('', [], []), Caption(None, [Plain([Str('Demonstration'), Space(), Str('of'), Space(), Str('simple'), Space(), Str('table'), Space(), Str('syntax.')])]), [(AlignRight(), ColWidthDefault()), (AlignLeft(), ColWidthDefault()), (AlignCenter(), ColWidthDefault()), (AlignDefault(), ColWidthDefault())], TableHead(('', [], []), [Row(('', [], []), [Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('Right')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('Left')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('Center')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('Default')])])])]), [TableBody(('', [], []), RowHeadColumns(0), [], [Row(('', [], []), [Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('12')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('12')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('12')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('12')])])]), Row(('', [], []), [Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('123')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('123')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('123')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('123')])])]), Row(('', [], []), [Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('1')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('1')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('1')])]), Cell(('', [], []), AlignDefault(), RowSpan(1), ColSpan(1), [Plain([Str('1')])])])])], TableFoot(('', [], []), []))])
```

--------------------------------

### Labeled Examples in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Labeled examples can be referenced elsewhere in the document using their label.

```markdown
(@good)  This is a good example.

As (@good) illustrates, ...
```

--------------------------------

### Pandoc: Gutenberg Conventions for Plain Output

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Example demonstrating Project Gutenberg conventions for `plain` output, such as all-caps for strong emphasis and underscores for regular emphasis. This is enabled by the `gutenberg` extension.

```markdown
This is **strong emphasis**.
This is *emphasis*.
```

--------------------------------

### Command-line Notebook Conversion

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/examples.md

Provides a Python script for a `main` entry point to convert markdown files to notebooks from the command line. It reads a markdown file, converts it, and saves it as a `.ipynb` file.

```python
import json
from pathlib import Path
import sys

def main():
    filename = sys.argv[1]
    doc = pandoc.read(file=filename)
    notebook = notebookify(doc)
    ipynb = Path(filename).with_suffix(".ipynb")
    with open(ipynb, "w", encoding="utf-8") as output:
        json.dump(notebook, output, ensure_ascii=False, indent=2)
```

```pycon
>>> import tempfile
>>> with tempfile.TemporaryDirectory() as tmp_dir: # doctest: +ELLIPSIS
...     md_path = Path(tmp_dir).joinpath("doc.md")
...     with open(md_path, "w", encoding="utf-8") as md_file:
...         _ = md_file.write(markdown)
...     sys.argv[:] = ["notebookify", str(md_path)]
...     main()
...     with open(md_path.with_suffix(".ipynb"), encoding="utf-8") as ipynb:
...         pprint.pprint(json.load(ipynb))
{'cells': [{'cell_type': 'markdown',
            'id': ...,
            'metadata': {},
            'source': ['# Hello world!']},
           {'cell_type': 'markdown',
            'id': ...,
            'metadata': {},
            'source': ['Print `Hello world!`:']},
           {'cell_type': 'code',
            'execution_count': None,
            'id': ...,
            'metadata': {}, 
            'outputs': [],
            'source': ['>>> print("Hello world!")']}],
 'metadata': {},
 'nbformat': 4,
 'nbformat_minor': 5}
```

--------------------------------

### Initialism as Paragraph Start (Python)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Pandoc's Python AST representation for a paragraph starting with an initialism and period.

```python
Pandoc(Meta({}), [Para([Str('B.'), Space(), Str('Russell'), Space(), Str('was'), Space(), Str('an'), Space(), Str('English'), Space(), Str('philosopher.')])])
```

--------------------------------

### Get Length of Pandoc Element

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/iteration.md

Shows how to get the number of items in a Pandoc element using the len() function.

```pycon
>>> len(doc)
2
>>> len(doc) == len(doc[:])
True

```

--------------------------------

### Footnote Style Citation Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

In a footnote style, citations can be rendered as footnotes. This example shows the footnote marker and its corresponding definition.

```markdown
Blah blah.[^1]

[^1]:  John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
    Susan Smith, "Flies," *Journal of Insects* (2000);
    Susan Smith, "Bees," *Journal of Insects* (2004).
```

--------------------------------

### Install Pandoc with Conda

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/getting-started.md

Installs Pandoc using the conda package manager, often used for managing scientific and data science packages.

```bash
$ conda install -c conda-forge pandoc
```

--------------------------------

### List Highlight Styles

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Use this command to see a list of available highlight styles for syntax highlighting.

```bash
pandoc --list-highlight-styles
```

--------------------------------

### Parse ATX-Style Headers

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Demonstrates parsing of ATX-style headers (using '#' symbols). Includes examples of level 2 and level 3 headers, and a header with a link and emphasis.

```python
"""
## A level-two header

### A level-three header ###
"""
# doctest: +PANDOC
```

```python
"# A level-one header with a [link](/url) and *emphasis*"
# doctest: +PANDOC
```

--------------------------------

### Using Defaults Files

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Defaults files can be placed in the user data directory and invoked using `--defaults` or `-d`.

```bash
pandoc --defaults letter
```

```bash
pandoc -dletter
```

--------------------------------

### Iterate with Path to Get Depth

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/iteration.md

Use `pandoc.iter(doc, path=True)` to iterate through document elements and get their path. The length of the path indicates the element's depth.

```pycon
>>> for elt, path in pandoc.iter(doc, path=True):
...     print(f"{len(path)} - {elt!r}")
0 - Pandoc(Meta({}), [Header(1, ('title', [], []), [Str('Title')]), Para([Str('Content')])])
1 - Meta({})
2 - {}
1 - [Header(1, ('title', [], []), [Str('Title')]), Para([Str('Content')])]
2 - Header(1, ('title', [], []), [Str('Title')])
3 - 1
3 - ('title', [], [])
4 - 'title'
4 - []
4 - []
3 - [Str('Title')]
4 - Str('Title')
5 - 'Title'
2 - Para([Str('Content')])
3 - [Str('Content')]
4 - Str('Content')
5 - 'Content'
```

--------------------------------

### ATX-style Headings in Markdown and Python

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Illustrates ATX-style headings in Markdown, showing level-two and level-three examples, and their corresponding Pandoc Python Abstract Syntax Tree (AST) representation.

```markdown
## A level-two heading

### A level-three heading ###
```

```python
Pandoc(Meta({}), [Header(2, ('a-level-two-heading', [], []), [Str('A'), Space(), Str('level-two'), Space(), Str('heading')]), Header(3, ('a-level-three-heading', [], []), [Str('A'), Space(), Str('level-three'), Space(), Str('heading')])])
```

--------------------------------

### Markdown YAML Metadata Block Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

A comprehensive example of a YAML metadata block in Markdown, including title, author, keywords, and a multi-paragraph abstract using literal block style.

```markdown
---
title:  'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...
```

--------------------------------

### Configure and Read Pandoc Settings

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/configuration.md

Combine configuration with reading settings to apply changes and immediately inspect the resulting configuration.

```python
config = pandoc.configure(auto=True, read=True)
```

--------------------------------

### Import Pandoc Library

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/configuration.md

Import the pandoc library to begin using its functionalities.

```python
import pandoc
```

--------------------------------

### Ordered List with Custom Start and Sublist (Python AST)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Represents the Pandoc AST for an ordered list starting at 9 with custom numbering and a sublist using lowercase roman numerals.

```python
Pandoc(Meta({}), [OrderedList((9, Decimal(), OneParen()), [[Plain([Str('Ninth')])], [Plain([Str('Tenth')])], [Plain([Str('Eleventh')]), OrderedList((1, LowerRoman(), Period()), [[Plain([Str('subone')])], [Plain([Str('subtwo')])], [Plain([Str('subthree')])]])]])])
```

--------------------------------

### Use KaTeX for HTML Math Rendering

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Integrates KaTeX for rendering TeX math in HTML. It requires a URL pointing to the KaTeX library; otherwise, it uses the KaTeX CDN.

```bash
--katex[=URL]
```

--------------------------------

### Fenced Code Block with Tildes

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Fenced code blocks start and end with a row of three or more tildes. The length of the ending row must be at least as long as the starting row. No indentation is required.

```text
    ~~~~~~~
    if (a > 3) {
      moveShip(5 * gravity, DOWN);
    }
    ~~~~~~~
```

--------------------------------

### Find all matching elements in HELLOWORLD_DOC

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/cookbook.md

Demonstrates using the find helper with `all=True` to retrieve lists of all Meta, Para, and Str elements from HELLOWORLD_DOC.

```pycon
>>> find(HELLOWORLD_DOC, Meta, all=True)
[Meta({})]
>>> find(HELLOWORLD_DOC, Para, all=True)
[Para([Str('Hello'), Space(), Str('world!')])]
>>> find(HELLOWORLD_DOC, Str, all=True)
[Str('Hello'), Str('world!')]
>>> find(HELLOWORLD_DOC, LineBreak, all=True)
[]
```

--------------------------------

### Footnote Citation Rendering in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Example of how citations might render in a footnote style.

```markdown
Blah blah.[^1]

[^1]:  John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
        Susan Smith, "Flies," *Journal of Insects* (2000);
        Susan Smith, "Bees," *Journal of Insects* (2004).
```

--------------------------------

### Pandoc: List Extensions for a Format

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Use this command to see which extensions are supported for a given format and which are enabled by default. Replace FORMAT with the desired format name.

```bash
pandoc --list-extensions=FORMAT
```

--------------------------------

### Author-Date Citation Rendering in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Example of how citations might render in an author-date style.

```markdown
Blah blah (Doe 1999, Smith 2000, 2004).
```

--------------------------------

### Configure Pandoc Path and Version

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/api.md

Explains the `configure` function for setting the Pandoc executable path, version, and pandoc-types version. Setting `auto=True` attempts to infer the path.

```python
pandoc.configure(path="/usr/bin/pandoc", version="2.14.2", pandoc_types_version="1.22.1")
```

--------------------------------

### Configure Geometry Package Options

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Set options for the 'geometry' package to control page margins and layout. Repeat for multiple options.

```yaml
---
geometry:
- top=30mm
- left=20mm
- heightrounded
...
```

--------------------------------

### Build a Pandoc Document Programmatically

Source: https://context7.com/boisgera/pandoc/llms.txt

Construct a Pandoc document from scratch using its type constructors. This example creates a simple document with a paragraph containing text and an ampersand.

```python
meta = Meta({})
inlines = [Str("Python"), Space(), Str("&"), Space(), Str("Pandoc")]
doc = Pandoc(meta, [Para(inlines)])
print(pandoc.write(doc).strip())
```

--------------------------------

### Parenthesized Year as List Item (Markdown)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Markdown example demonstrating how a parenthesized year can be interpreted as a list item.

```markdown
(C) 2007 Joe Smith
```

--------------------------------

### Set Hyperref Package Options

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Configure options for the 'hyperref' package, such as 'linktoc=all'. Repeat for multiple options.

```yaml
---
hyperrefoptions:
- linktoc=all
- pdfwindowui
- pdfpagemode=FullScreen
...
```

--------------------------------

### Markdown Compact Bullet List

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

A simple Markdown bullet list example. Each item is treated as a single block.

```markdown
* one
* two
* three
```

--------------------------------

### Limiting Heap Size for Pandoc Processes

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Demonstrates how to limit the heap size for Pandoc processes using GHC runtime system options to prevent potential Denial of Service attacks.

```bash
+RTS -M512M -RTS
```

--------------------------------

### Verbatim Text Example

Source: https://github.com/boisgera/pandoc/blob/master/src/pandoc/tests.md

Demonstrates how Pandoc handles verbatim text and special characters within code blocks.

```doctest
>>> "What is the difference between `>>=` and `>>`?" # doctest: +PANDOC
Pandoc(Meta(map()), [Para([Str(u'What'), Space(), Str(u'is'), Space(), Str(u'the'), Space(), Str(u'difference'), Space(), Str(u'between'), Space(), Code((u'', [], []), u'>>='), Space(), Str(u'and'), Space(), Code((u'', [], []), u'>>'), Space(), Str(u'?')])])
```

```doctest
>>> "Here is a literal backtick `` ` ``." # doctest: +PANDOC
Pandoc(Meta(map()), [Para([Str(u'Here'), Space(), Str(u'is'), Space(), Str(u'a'), Space(), Str(u'literal'), Space(), Str(u'backtick'), Space(), Code((u'', [], []), u'`'), Space(), Str(u'.')])])
```

```doctest
>>> "This is a backslash followed by an asterisk: `\*`." # doctest: +PANDOC
Pandoc(Meta(map()), [Para([Str(u'This'), Space(), Str(u'is'), Space(), Str(u'a'), Space(), Str(u'backslash'), Space(), Str(u'followed'), Space(), Str(u'by'), Space(), Str(u'an'), Space(), Str(u'asterisk:'), Space(), Code((u'', [], []), u'\*'), Space(), Str(u'.')])])
```

```doctest
>>> "`<$>`{.haskell}" # doctest: +PANDOC
Pandoc(Meta(map()), [Para([Code((u'', [u'haskell'], []), u'<$>')])])
```

--------------------------------

### pandoc.configure

Source: https://context7.com/boisgera/pandoc/llms.txt

Controls which Pandoc binary the library uses and what version of `pandoc-types` is assumed. Auto-configuration discovers the `pandoc` executable on `PATH`. Manual configuration is useful for reproducible builds, testing, or environments without a `pandoc` binary.

```APIDOC
## `pandoc.configure` — Configure the Pandoc executable

Controls which Pandoc binary the library uses and what version of `pandoc-types` is assumed. Auto-configuration (the default) automatically discovers the `pandoc` executable on `PATH`. Manual configuration is useful for reproducible builds, testing, or environments without a `pandoc` binary.

```python
import pandoc

# Auto-configure from the pandoc binary found on PATH (default behavior)
pandoc.configure(auto=True)

# Read the current configuration (without changing it)
config = pandoc.configure(read=True)
print(config)
# => {'auto': True, 'path': '/usr/bin/pandoc', 'version': '3.2.1',
#     'pandoc_types_version': '1.23.1'}

# Configure using an explicit path to a pandoc binary
pandoc.configure(path="/usr/local/bin/pandoc")

# Configure for a specific pandoc version (no binary needed for JSON I/O)
pandoc.configure(version="2.18")

# Configure for a specific pandoc-types version directly
pandoc.configure(pandoc_types_version="1.22.2")

# Reset to unconfigured state
pandoc.configure(reset=True)
assert pandoc.configure(read=True) is None

# Auto-configure and read back in one call
config = pandoc.configure(auto=True, read=True)
print(config["version"])   # e.g. '3.2.1'
print(config["path"])      # e.g. '/usr/bin/pandoc'
```
```

--------------------------------

### List Highlight Languages

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Use this command to get a list of language names that pandoc recognizes for syntax highlighting.

```bash
pandoc --list-highlight-languages
```

--------------------------------

### Create a Pandoc Document

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/iteration.md

Creates a simple Pandoc document with metadata and a paragraph.

```python
meta = Meta({})
blocks = [Para([Str('Hello'), Space(), Str('world!')])]
doc = Pandoc(meta, blocks)

```

--------------------------------

### Read Document with Pandoc CLI

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/index.md

Demonstrates how to use the Pandoc command-line interface to read a simple text string and output its Pandoc document model representation.

```bash
$ echo "Hello world!" | python -m pandoc read 
Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
```

--------------------------------

### Pandoc AST for Footnotes

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

This Python code represents the Pandoc Abstract Syntax Tree (AST) for the Markdown footnotes example.

```python
Pandoc(Meta({}), [Para([Str('Here'), Space(), Str('is'), Space(), Str('a'), Space(), Str('footnote'), Space(), Str('reference,'), Note([Para([Str('Here'), Space(), Str('is'), Space(), Str('the'), Space(), Str('footnote.')])]), Space(), Str('and'), Space(), Str('another.'), Note([Para([Str('Here’s'), Space(), Str('one'), Space(), Str('with'), Space(), Str('multiple'), Space(), Str('blocks.')]), Para([Str('Subsequent'), Space(), Str('paragraphs'), Space(), Str('are'), Space(), Str('indented'), Space(), Str('to'), Space(), Str('show'), Space(), Str('that'), Space(), Str('they'), SoftBreak(), Str('belong'), Space(), Str('to'), Space(), Str('the'), Space(), Str('previous'), Space(), Str('footnote.')]), CodeBlock(('', [], []), '{ some.code }'), Para([Str('The'), Space(), Str('whole'), Space(), Str('paragraph'), Space(), Str('can'), Space(), Str('be'), Space(), Str('indented,'), Space(), Str('or'), Space(), Str('just'), Space(), Str('the'), Space(), Str('first'), SoftBreak(), Str('line.'), Space(), Str('In'), Space(), Str('this'), Space(), Str('way,'), Space(), Str('multi-paragraph'), Space(), Str('footnotes'), Space(), Str('work'), Space(), Str('like'), SoftBreak(), Str('multi-paragraph'), Space(), Str('list'), Space(), Str('items.')])])]), Para([Str('This'), Space(), Str('paragraph'), Space(), Str('won’t'), Space(), Str('be'), Space(), Str('part'), Space(), Str('of'), Space(), Str('the'), Space(), Str('note,'), Space(), Str('because'), Space(), Str('it'), SoftBreak(), Str('isn’t'), Space(), Str('indented.')])])
```

--------------------------------

### Configure Pandoc with Specific Path

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/configuration.md

Specify the exact path to the pandoc executable for configuration.

```python
pandoc.configure(path='/usr/bin/pandoc')
```

--------------------------------

### Markdown Input for Theorem Conversion

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/examples.md

Example Markdown content containing a div tagged as a theorem, intended for conversion to LaTeX.

```markdown
markdown = r"""
<div id='cauchy-formula' class='theorem'>
$$f(z) = \frac{1}{i2\pi} \int \frac{f(w)}{w-z}\, dw$$

```

--------------------------------

### Setting SOURCE_DATE_EPOCH for Reproducible Builds

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Example of setting the SOURCE_DATE_EPOCH environment variable to ensure reproducible builds by using a specific timestamp.

```bash
SOURCE_DATE_EPOCH=1234567890 pandoc input.docx -o output.docx
```

--------------------------------

### Setting SOURCE_DATE_EPOCH for Reproducible Builds

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Example of setting the SOURCE_DATE_EPOCH environment variable to ensure reproducible builds by using a specific timestamp.

```bash
SOURCE_DATE_EPOCH=1678886400 pandoc input.md -o output.epub
```

--------------------------------

### Print Highlight Style to JSON

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Use this command to generate a JSON theme file for a specific highlight style, which can then be modified.

```bash
pandoc --print-highlight-style pygments > my.theme
```

--------------------------------

### Man Page Title Extraction (Basic)

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL-patched.txt

Example of a title line for man page extraction, specifying the title and section number.

```text
% PANDOC(1)
```

--------------------------------

### Basic Grid Table in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Illustrates the basic syntax for creating a grid table in Markdown, including headers and cells with list elements.

```markdown
: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+
```

--------------------------------

### Ignore Arguments Example

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/manual/MANUAL.txt

Illustrates how --ignore-args affects argument processing, showing an equivalent command without the ignored arguments.

```bash
pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
is equivalent to
pandoc -o foo.html -s
```

--------------------------------

### Multiline Table Example in Markdown

Source: https://github.com/boisgera/pandoc/blob/master/mkdocs/markdown.md

Demonstrates a multiline table with a header and caption in Markdown format. Ensure rows are separated by blank lines and use dashes for header/footer separators.

```markdown
-------------------------------------------------------------
 Center Aligned Default Right Left
 Header Aligned Aligned Aligned
----------- ------- --------------- -------------------------
 First row 12.0 Example of a row that

 Second row 5.0 Here's another one. Note
 the blank line between
 rows.
-------------------------------------------------------------

 Table: Here's the caption. It, too, may span
 multiple lines.
```