Pypandoc

Warnings

• breaking Python 2 support was officially dropped in pypandoc v1.8. Users on Python 2 must use an older version of pypandoc.
  Fix: Upgrade to Python 3 or pin pypandoc version to <1.8.
• breaking The `pypandoc.convert()` function was deprecated in v1.7.0 and removed in v1.8. Direct usage will raise an error.
  Fix: Replace `pypandoc.convert(source, to, format, ...)` with `pypandoc.convert_file(source_path, to_format, outputfile, ...)` for files or `pypandoc.convert_text(source_string, to_format, format, ...)` for strings.
• gotcha Pypandoc requires a working Pandoc installation. If you install `pypandoc` (without `_binary` or `[tinytex]`), you must install Pandoc separately via your system's package manager or manually. An `OSError` will be raised if Pandoc is not found.
  Fix: Install `pandoc` on your system, use `pip install pypandoc_binary`, or utilize `pypandoc.download_pandoc()` to install it through the library. Ensure Pandoc's executable is in your system's PATH.
• gotcha Pandoc's sandbox mode (for security) is enabled by default for Pandoc versions >= 2.15 when used via pypandoc v1.7.0 and newer. This might affect how certain filters or file operations behave.
  Fix: Review Pandoc's documentation on sandbox mode. If necessary, you can typically disable it via `extra_args` or library configuration, though it's recommended to understand the security implications.
• gotcha When passing `extra_args` to `pypandoc.convert_file` or `convert_text`, arguments and their values (like `-V key=value`) must be passed as separate items in a list due to `subprocess.Popen` behavior.
  Fix: Instead of `extra_args='-V key=value'`, use `extra_args=['-V', 'key=value']`.
• gotcha For PDF conversion, Pandoc requires a LaTeX distribution (e.g., TeX Live, MiKTeX). Installing `pypandoc[tinytex]` simplifies this by automatically downloading and managing TinyTeX, but if not used, manual LaTeX setup is required.
  Fix: Install `pypandoc[tinytex]` for automatic setup, or install a full LaTeX distribution manually and ensure it's in your system's PATH.

Install

• pip install pypandoc Basic installation (requires pre-installed Pandoc)
• pip install pypandoc_binary Includes Pandoc binary (for Windows/macOS/some Linux)
• pip install pypandoc[tinytex] Includes Pandoc & TinyTeX (for seamless PDF conversion)
• conda install -c conda-forge pypandoc Conda installation (includes Pandoc)

Imports

• convert_file

  import pypandoc
  pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf')

  The `convert()` function was deprecated in v1.7.0 and removed in v1.8. Use `convert_file()` for file-based conversion or `convert_text()` for string-based conversion.
• convert_text

  import pypandoc
  html_output = pypandoc.convert_text('# Hello', 'html', format='md')

  Use `convert_text()` for converting strings. It expects unicode or utf-8 encoded bytes and returns a unicode string.

Quickstart

This quickstart demonstrates how to convert a Markdown file to PDF and a Markdown string to HTML using `pypandoc`. For PDF conversion, installing `pypandoc[tinytex]` simplifies LaTeX setup. If `pypandoc_binary` is not used, ensure Pandoc is installed on your system or use `pypandoc.download_pandoc()`.

import pypandoc
import os

# Ensure pandoc is available (optional if using pypandoc_binary or pypandoc[tinytex])
# pypandoc.download_pandoc() # uncomment if you installed pypandoc without binary and don't have pandoc

# Create a dummy markdown file
with open('input.md', 'w') as f:
    f.write('# Hello from Pypandoc\n\nThis is a test document.')

# Convert markdown file to PDF (requires pandoc and a LaTeX distribution like TinyTeX)
# For seamless PDF conversion, install with `pip install pypandoc[tinytex]`
pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf')
print("Converted input.md to output.pdf")

# Convert markdown string to HTML
html_output = pypandoc.convert_text('# Another Title\n\nSome **bold** text.', 'html', format='md')
print("Converted Markdown string to HTML:")
print(html_output)

# Clean up dummy files
os.remove('input.md')
os.remove('output.pdf')