pptx2md Documentation

By default, all PPTX titles are parsed as level 1 markdown titles. To create a hierarchical table of contents, provide a predefined title list using the -t argument.

Title File Format: Use indentation (spaces) to define heading levels. The number of spaces in the first indented line determines the indentation unit.

Example titles.txt:

Heading 1
  Heading 1.1
    Heading 1.1.1
  Heading 1.2

Matching Logic:

• Titles are matched using fuzzy matching (score must be > 92).
• Unmatched titles default to the deepest header level.
• Similar titles (score > 92) are omitted by default unless --keep-similar-titles is used.

Usage:

pptx2md [filename] -t titles.txt

Use the pptx2md command followed by the path to your .pptx file.

Note: Older .ppt files are not supported; convert them to .pptx before use.

By default, the output is saved as out.md and extracted images are placed in an /img/ folder.

pptx2md [pptx filename]

To install pptx2md, ensure you have Python version 3.10 or later and pip installed on your system, then run:

pip install pptx2md

The ParsedPresentation object is the top-level container for the results of a conversion. It contains a list of Slide objects.

A Slide can be one of two types:

1. GeneralSlide: A standard slide containing a list of elements (Title, Paragraph, etc.) and optional notes.
2. MultiColumnSlide: A slide with a preface section followed by multiple columns, each containing its own elements.

Element Types (ElementType):

• Title
• ListItem
• Paragraph
• Image
• Table

You can integrate pptx2md into your Python projects using the convert function and the ConversionConfig class. The ConversionConfig object accepts the same parameters as the CLI.

from pptx2md import convert, ConversionConfig
from pathlib import Path

# Basic usage
convert(
    ConversionConfig(
        pptx_path=Path('presentation.pptx'),
        output_path=Path('output.md'),
        image_dir=Path('img'),
        disable_notes=True
    )
)

The ConversionConfig class (a Pydantic model) defines the settings for the PowerPoint to Markdown conversion process. Use it to specify input/output paths and toggle various processing features like image extraction, color tags, or specific markdown flavors.

Key Configuration Options:

• pptx_path: Path to the source .pptx file.
• output_path: Path where the markdown file will be saved.
• image_dir: Directory for extracted images.
• disable_image: If True, skips image extraction.
• enable_slides: If True, delineates slides using \n---\n.
• is_wiki, is_mdk, is_qmd: Toggles for specific markdown formats (TiddlyWiki, Madoko, or Quarto).
• custom_titles: A dictionary mapping custom titles to their heading levels.
• try_multi_column: Enables detection of multi-column slide layouts.

The Formatter class and its subclasses are responsible for converting ParsedPresentation data into specific text formats. You can instantiate a specific formatter based on your target output format and call its .output(presentation_data) method.

Available formatters:

• MarkdownFormatter: Standard Markdown output.
• WikiFormatter: Wikitext format.
• MadokoFormatter: Madoko-flavored Markdown (includes a Table of Contents).
• QuartoFormatter: Quarto Markdown specifically optimized for revealjs presentations.

Each formatter requires a ConversionConfig object during initialization to handle paths and formatting preferences (like color or escaping).

The convert function is the primary entry point for programmatically converting PowerPoint (.pptx) files into Markdown, Wiki, Madoko, or Quarto formats. It accepts a ConversionConfig object which defines the input path, output path, and formatting preferences.

Workflow:

1. If config.title_path is provided, custom titles are prepared from that path.
2. The PPTX file is loaded.
3. The content is parsed into an Abstract Syntax Tree (AST).
4. If the output_path ends in .json, the AST is saved as a JSON file.
5. Otherwise, the AST is passed to a formatter (Wiki, Madoko, Quarto, or standard Markdown) based on the configuration flags, and the resulting document is written to the output_path.