fast-pptx

Quickly make a PowerPoint presentation from a directory of code snippets, CSV files, TSV files, Graphviz DOT files, Mermaid mmd files, images, PDFs, and URLs. fast-pptx converts the CSV and TSV files to Markdown tables, renders the DOT and mmd files, creates high-resolution images from the PDFs, captures high-resolution screenshots of the websites listed in sites.txt, and then builds a Markdown presentation file for input to Pandoc. The Markdown file is then converted to PowerPoint presentations using templates that preserve syntax highlighting and make effective use of slide space. You can edit the Markdown to add content and regenerate the presentations using the included pandoc.sh script that is generated, or you can edit the presentations in PowerPoint.

The intended workflow is to start a presentation by deciding which figures, screenshots, tables, and code snippets you want to show, place those source files together in one input directory, and let fast-pptx build the first draft of the slide deck around them. The generated slides give you a presentation skeleton populated with the visual and technical material you selected, which you can then open in PowerPoint to add the explanatory text, reorder slides, refine formatting, and make the deck presentation-ready.

For example, start with an input directory that contains a sites.txt file with URLs to capture as screenshots:

https://github.com/sindresorhus/pageres-cli

It can also contain a Graphviz .dot file such as:

graph TD
    A[Start] --> B[Task 1]
    B --> C{Decision 1}
    C -->|Option 1| D[Task 2]
    D --> E[Task 3]
    C -->|Option 2| F[Task 4]
    F --> G[Task 5]

    classDef default fill:#f9f,stroke:#333,stroke-width:4px;
    classDef decision fill:#fdd,stroke:#f66,stroke-width:2px,stroke-dasharray: 5, 5;
    class C decision

And it can contain a source code file such as this R script:

#!/usr/bin/env Rscript

# Simulate some data
set.seed(42)
x <- 1:100
y <- x * 2 + rnorm(100, mean = 0, sd = 50)

# Create a linear model
model <- lm(y ~ x)

# Summary of the model
summary(model)

# Plot the data and the model
plot(x, y, main = "Linear Regression Model", xlab = "X", ylab = "Y")
abline(model, col = "red")

# Print the coefficients
print(coef(model))

Those inputs are then turned into slides like these:

See the sample output for the full collection of slides produced by the included sample input files.

Author

Paul Stothard

Quick start

Install dependencies and download fast-pptx, place your source files into a single directory and then run fast-pptx:

./fast-pptx.sh -i input-directory -o output-directory

The source files are used to build content, which is added to a PowerPoint presentation created in the output directory. If code snippets are included in the input directory, then a second presentation is created with the code snippets converted to syntax-highlighted code blocks. A third presentation, slides_merged.pptx, is then created automatically by fixing the generated .pptx output and appending the code deck to the regular deck while preserving the appended slides' source formatting. If there are no code slides to append, slides_merged.pptx is created as a fixed copy of slides.pptx.

The slides can then be edited in PowerPoint to change the order of slides, add or modify text, adjust font sizes, and choose designs for specific slides (using PowerPoint Designer by choosing Design > Design Ideas on the ribbon). The file size can then be reduced using File > Compress Pictures....

You can also edit or replace the theme.pptx and theme_code_blocks.pptx files that are written to the output folder's includes directory and then re-generate the slides using the pandoc.sh script that is included in the output folder. These reference .pptx files serve as templates. Pandoc will use these files as a basis for creating the new presentations. This means that instead of the default PowerPoint styles, your presentation will inherit the styles defined in the reference documents — including fonts, colors, bullet styles, and other formatting. A separate reference document is used for the code blocks to allow for smaller fonts and different colors to be specified. The generated pandoc.sh also re-runs the PPTX fix/merge step by calling the installed merge_pptx.py helper from the fast-pptx scripts directory.

fast-pptx also generates slides_merged.pptx, which appends slides_code_blocks.pptx to slides.pptx while preserving the code deck's slide layouts, master, and theme. When no code deck is generated, slides_merged.pptx is still created as the repaired regular deck output.

Using the fast-pptx Docker image

Pull the Docker image:

docker pull pstothard/fast-pptx

Run the Docker image against the included sample input files (after cloning the repository):

docker run --rm \
  -v "$(pwd)":/data \
  -u "$(id -u)":"$(id -g)" \
  -w /data \
  pstothard/fast-pptx -i sample_input -o sample_output_docker

The output files are written to the sample_output_docker directory on the host system.

To use your own input directory:

docker run --rm \
  -v "$(pwd)":/data \
  -u "$(id -u)":"$(id -g)" \
  -w /data \
  pstothard/fast-pptx -i my_input -o my_output

To see progress messages add the -v flag:

docker run --rm \
  -v "$(pwd)":/data \
  -u "$(id -u)":"$(id -g)" \
  -w /data \
  pstothard/fast-pptx -v -i my_input -o my_output

To view all options:

docker run --rm pstothard/fast-pptx --help

Supported source file types for the input directory

Type	Filename	Converted to	PowerPoint Content Generated
Code Snippet	*.<language>	Not Converted	Two slides (one-column and two-column) per code snippet file showing syntax-highlighted code
CSV File	*.csv	Markdown Table	Two slides (one-column and two-column) per CSV file showing the content as a table
Dot File for Graphviz	*.dot	PNG and Resized PNG	Two slides (one-column and two-column) per DOT file showing the rendered graph
GIF File	*.gif	Not Converted	Two slides (one-column and two-column) per GIF file showing the GIF
JPG File	*.jpg or *.jpeg	PNG and Resized PNG	Two slides (one-column and two-column) per JPG or JPEG file showing the resized PNG
MMD File for Mermaid	*.mmd	PNG and Resized PNG	Two slides (one-column and two-column) per MMD file showing the rendered graph
PDF File	*.pdf	PNG and Resized PNG	Two slides (one-column and two-column) per PDF file showing the resized PNG
PNG File	*.png	Resized PNG	Two slides (one-column and two-column) per PNG file showing the resized PNG
SVG File	*.svg	PNG and Resized PNG	Two slides (one-column and two-column) per SVG file showing the resized PNG
TIFF File	*.tiff	PNG and Resized PNG	Two slides (one-column and two-column) per TIFF file showing the resized PNG
TSV File	*.tsv	Markdown Table	Two slides (one-column and two-column) per TSV file showing the content as a table
URLs (one per line)	sites.txt	PNG and Resized PNG for Each Site	Two slides (one-column and two-column) per web site URL showing the resized PNG screenshot for the site

Output directory structure

outdir
├── slides.pptx
├── slides.md
├── slides_code_blocks.pptx  # when code slides are generated
├── slides_code_blocks.md
├── slides_merged.pptx
├── pandoc.sh
└── includes
    ├── theme.pptx
    ├── theme_code_blocks.pptx
    └── resized

Install

fast-pptx requires the following:

• csv2md
• Graphviz
• ImageMagick (magick or convert)
• Node.js
• Playwright (with Chromium) for website screenshots
• pandoc
• poppler
• Python 3 for merge_pptx.py (generated PPTX repair and deck merge)
• svgexport
• mermaid-cli

The script also assumes standard Unix command-line tools that are normally bundled with macOS or Linux, such as awk, basename, cut, dirname, du, find, grep, sed, and sh.

On macOS these can be installed as follows:

brew install graphviz
brew install imagemagick
brew install node
brew install pandoc
brew install poppler
brew install python
npm install -g mermaid.cli
npm install -g csv2md
npm install -g svgexport

Website screenshots are captured using the included scripts/capture-site.mjs helper. It requires Playwright and a one-time Chromium install (run once from the repo root after cloning):

npm install --prefix scripts
npx --prefix scripts playwright install chromium

Clone the repository, install Node dependencies, and test fast-pptx.sh:

git clone git@github.com:paulstothard/fast-pptx.git
cd fast-pptx
npm install --prefix scripts
npx --prefix scripts playwright install chromium
./fast-pptx.sh -i sample_input -o sample_output

Or download a release and test fast-pptx.sh, for example:

unzip fast-pptx-x.y.z.zip
cd fast-pptx-x.y.z
npm install --prefix scripts
npx --prefix scripts playwright install chromium
./fast-pptx.sh -i sample_input -o sample_output

Add fast-pptx.sh to PATH or continue to specify the path to fast-pptx.sh to run.

Command-line options

USAGE:
   fast-pptx.sh -i DIR -o DIR [Options]

DESCRIPTION:
   Quickly make a PowerPoint presentation from a directory of code snippets, 
   CSV files, TSV files, Graphviz DOT files, Mermaid mmd files, images, PDFs, 
   and URLs.

REQUIRED ARGUMENTS:
   -i, --input DIR
      Directory of presentation content.
   -o, --output DIR
      Directory for output files.
OPTIONAL ARGUMENTS:
   -cr, --cron
      Run silently unless error is encountered.
   -f, --force
      Overwrite existing Markdown and PowerPoint files in output directory.
   -h, --help
      Display this message.
   -nc, --no-colour
      Disable colour messages.
   -r, --reprocess
      Reprocess input files even if conversion files exist in output directory.
   -v, --verbose
      Display verbose messages.