Pandoc Python Library

All concrete Pandoc elements (e.g., Pandoc, Para, Str) behave like list-like containers. The items within these containers are the arguments passed to their constructors. You can use standard Python indexing, slicing, and assignment to access or modify their contents.

Key container behaviors:

• Random Access: Use doc[index] or doc[start:stop] to access elements. Use assignment doc[index] = new_element to modify them.
• Length: len(element) returns the number of items in the container.
• Equality: Elements can be compared using ==. Equality checks both the type and the contents (recursively).
• Membership: Use the in operator to check if a specific element exists within a container.
• Iteration: You can use a standard for elt in element: loop to iterate over the immediate children of a Pandoc element.

import pandoc
from pandoc.types import *

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

# Random access and modification
print(doc[0])          # Meta({})
print(doc[1][0][0])   # Str('Hello')

doc[1] = [Para([Str('New')])]
print(doc)

Block quotations are created by preceding one or more lines with a > character and an optional space.

Syntax Styles

• Standard: Every line in the block is preceded by >.
• Lazy: The > character is only required on the first line of each block.

Nesting and Indentation

• Nesting: Block quotes can be nested by using multiple > characters (e.g., > > text).
• Indented Code inside Quotes: To include an indented code block within a block quote, use five spaces after the > character to account for the marker and the optional space.

Important Extension: blank_before_blockquote

By default, Pandoc requires a blank line before a block quote (unless it is at the start of the document) to prevent accidental triggers from line-wrapped text. If this extension is enabled, a > immediately following text without a blank line will not be treated as a nested block quote.

> This is a block quote.
>
> > A nested block quote.

>     indented code block

A Pandoc object is structured as a sequence where the first element (index 0) is the Meta object and the subsequent elements (starting at index 1) are the document Block elements.

To access metadata, you access the Meta object, then its internal dictionary. To access content, you access the list of blocks.

Note: Direct index access is fragile and can raise KeyError or IndexError if the document structure differs from your expectation. It is recommended to use .get() on the metadata dictionary and perform isinstance() checks to ensure the structure matches your assumptions.

# Accessing metadata 'date'
meta = doc[0] # Pandoc(Meta, [Block])
meta_dict = meta[0] # Meta({Text: MetaValue})
date = meta_dict.get("date")

# Accessing the first header
blocks = doc[1] # [Block]
header = blocks[0]
# header is a Header(Int, Attr, [Inline])
# header[2] contains the inlines

Pandoc supports multiple link styles:

• Automatic Links: <http://google.com> or <email@address.com>.
• Inline Links: [text](url "title").
• Reference Links: [label][id] where [id]: url "title" is defined elsewhere.
• Shortcut Reference Links: [label] where [label]: url is defined elsewhere (requires shortcut_reference_links extension).
• Internal Links: [text](#anchor) or [text] with a corresponding [anchor]: #anchor definition.

>>> """
... This is an [inline link](/url), and here's [one with
... a title](http://fsf.org "click here for a good time!"
... """
... # doctest: +PANDOC
    Pandoc(Meta(map()), [Para([Str(u'This'), Space(), Str(u'is'), Space(), Str(u'an'), Space(), Link((u'', [], []), [Str(u'inline'), Space(), Str(u'link')], u'/url'), Str(u','), Space(), Str(u'and'), Space(), Str(u"here's"), Space(), Str(u'[one'), Space(), Str(u'with'), SoftBreak(), Str(u'a'), Space(), Str(u'title](http://fsf.org'), Space(), Str(u'"click'), Space(), Str(u'here'), Space(), Str(u'for'), Space(), Str(u'a'), Space(), Str(u'good'), Space(), Str(u'time!')])])

Pandoc provides directives to control text alignment and line breaking.

• Nesting (^): Use the ^ directive to ensure subsequent lines of a multi-line variable are indented to align with the first line.
• Breakable Spaces (~): By default, spaces in templates are not breakable. Wrap text in $~$ ... $~$ to allow the renderer to break lines at those spaces.
• Automatic Nesting: If a variable is on its own line, preceded by whitespace and not followed by other text, multi-line values are automatically nested.

Example:

# Nesting
$item.number$  $^$$item.description$

# Breakable spaces
$~$This long line may break.$~$

$item.number$  $^$$item.description$ ($item.price$)

$item.number$  $^$$item.description$ ($item.price$)
               (Available til $item.sellby$.)

$~$This long line may break if the document is rendered with a short line length.$~$