Pandoc Documents for Python

Warnings

• breaking The Python `pandoc` library is a thin wrapper and does not bundle the Pandoc executable. Users MUST install the Pandoc command-line tool separately (e.g., via `conda install pandoc`, `sudo apt install pandoc`, or `brew install pandoc`). Failure to do so will result in runtime errors as the Python library will not find the `pandoc` binary.
  Fix: Ensure the Pandoc executable is installed on your system and accessible in the system's PATH before using the Python `pandoc` library.
• gotcha The `pandoc` Python library should not be confused with `pypandoc`. While both are Python wrappers for Pandoc, `pypandoc` offers a `pypandoc_binary` package that bundles the Pandoc executable, whereas `pandoc` (this library) always requires a separate installation of the underlying Pandoc tool.
• gotcha When programmatically interacting with the Pandoc executable (e.g., via Python's `subprocess` module or the `pandoc` library's underlying calls), command-line arguments, especially those with values, must be passed as distinct items in a list. Combining them into a single string (e.g., `'-Vtitle="My Title"'`) can lead to incorrect parsing by Pandoc. Instead, use `['-V', 'title="My Title"']`.
  Fix: Always pass command-line arguments as separate list items to ensure correct parsing by the Pandoc executable. Utilize `shlex.split()` for robust conversion of command strings to lists if needed.
• breaking The underlying Pandoc executable (version 3.1 and later) changed how it parses code block attributes. The syntax ````{lang}` (without a leading dot) is no longer interpreted as a language class but as a literal string. The correct syntax for specifying a language class is ````{.lang}````. This change in the Pandoc executable can affect how the Python `pandoc` library processes markdown documents.
  Fix: Update Markdown documents to use ````{.lang}```` for code block language attributes when targeting Pandoc executable versions 3.1 or newer. If processing older documents, be aware of potential parsing differences.
• gotcha The Python `pandoc` library is tested against specific versions of the Pandoc executable. While it might issue a warning for unsupported Pandoc executable versions instead of failing, using an incompatible version could lead to unexpected behavior or incorrect document transformations due to differences in the underlying document model.
  Fix: Refer to the Python `pandoc` library's documentation or changelog for the Pandoc executable versions it is officially tested against and supports. Ensure your installed Pandoc executable matches a supported version range.

Install

• pip install --upgrade pandoc Install Python library
• conda install -c conda-forge pandoc Install Pandoc executable (Conda)
• sudo apt install pandoc Install Pandoc executable (Debian/Ubuntu)
• brew install pandoc Install Pandoc executable (macOS Homebrew)

Imports

• pandoc

  import pandoc

  Main module for reading, writing, and manipulating Pandoc documents.
• types

  from pandoc.types import Str, Space, Para, Meta

  Provides access to the Abstract Syntax Tree (AST) types for fine-grained document manipulation.

Quickstart

This quickstart demonstrates how to read a Markdown string into a Pandoc document object, access and modify its Abstract Syntax Tree (AST) using `pandoc.types`, and then write the modified document back to a Markdown string. This showcases the core functionality for programmatic document manipulation.

import pandoc
from pandoc.types import Str, Space, Para, Meta

# Read a simple markdown string into a Pandoc document object
text = "Hello world!"
doc = pandoc.read(text)
print(f"Initial document: {doc}")

# Access and modify an element in the document's Abstract Syntax Tree (AST)
# For "Hello world!", doc is Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
# The paragraph is at doc[1][0]
# The 'world!' string is at doc[1][0][2][0]
paragraph = doc[1][0]

# Modify the 'world!' string to 'Python!'
# The Str object is at paragraph[2] (0: Str('Hello'), 1: Space(), 2: Str('world!'))
# The actual string value is the first element of the Str tuple: Str('world!')[0]
paragraph[2][0] = 'Python!'

# Write the modified document back to a markdown string
modified_text = pandoc.write(doc)
print(f"Modified document text: {modified_text.strip()}")

# Example of converting to a different format (requires actual pandoc executable)
# doc_to_convert = pandoc.read("# My Title\n\nHello from Pandoc!", format='markdown')
# html_output = pandoc.write(doc_to_convert, format='html')
# print(f"HTML output:\n{html_output}")