org-pdf-slide-show

Show specific PDF pages as inline images in org-mode.

What is this?

Ever wanted to reference a specific slide from a PDF deck right inside your org notes? This package does that. Drop a pdfslide link pointing to a PDF + page number, and the page shows up as an inline image.

Pages are extracted as PNGs and cached locally – they only get extracted once, so saving the buffer a second time won’t redo the work.

It also auto-inserts a [[file:...]] image link below each pdfslide link on save, so the images show up on GitHub and anywhere else org files are rendered – even without this package installed.

Quick example

[[pdfslide:./lectures/intro.pdf::3]]

That shows page 3 of intro.pdf inline. You can add a description too:

[[pdfslide:./lectures/intro.pdf::3][Title slide]]

The extracted image ends up at ./lectures/intro-slides/page-3.png.

When you save, the package also inserts a companion link automatically:

[[pdfslide:./lectures/intro.pdf::3]]
[[file:lectures/intro-slides/page-3.png]]

That [[file:...]] line is what makes the image render on GitHub, Gitea, or any org viewer. You don’t need to write it yourself – the package handles it. It won’t duplicate on repeated saves either.

Requirements

• Emacs 27.1+
• Org 9.0+
• pdftoppm (ships with poppler-utils)

Installing pdftoppm

Most Linux distros have it in repos already:

# fedora/rhel
sudo dnf install poppler-utils

# debian/ubuntu
sudo apt install poppler-utils

# arch
sudo pacman -S poppler

# macos
brew install poppler

Check it works: pdftoppm -v

Installation

Clone the repo somewhere and point your config at it:

(add-to-list 'load-path "~/path/to/org-pdf-slide-show")
(require 'org-pdf-slide-show)
(add-hook 'org-mode-hook #'org-pdf-slide-show-mode)

Or with use-package:

(use-package org-pdf-slide-show
  :load-path "~/path/to/org-pdf-slide-show"
  :hook (org-mode . org-pdf-slide-show-mode))

or with Doom Emacs: put this code in packages.el

(package! org-pdf-slide-show)

Then run doom sync.

Usage

1. Write a link: [[pdfslide:./deck.pdf::1]]
2. Save (C-x C-s)
3. The page gets extracted and displayed inline

If you don’t want to save, M-x org-pdf-slide-show-refresh does the same thing manually. M-x org-pdf-slide-show-clear hides all the overlays.

Clicking a link (C-c C-o) opens the PDF at that page in pdf-tools or doc-view.

Configuration

You can tweak these if the defaults don’t work for you:

;; bump up DPI for sharper images (default 150)
(setq org-pdf-slide-show-dpi 200)

;; wider inline display (default 600px)
(setq org-pdf-slide-show-image-width 800)

;; change the cache folder suffix (default "-slides")
;; intro.pdf -> intro-slides/
(setq org-pdf-slide-show-cache-suffix "-slides")

How it works

The package registers a custom org link type pdfslide. When you save an org buffer (with the mode active), it:

1. Finds all pdfslide links
2. For each one, checks if the PNG is already cached
3. If not, runs pdftoppm to extract just that page
4. Inserts a [[file:...]] companion link below each pdfslide link (for GitHub/web rendering)
5. After saving, puts image overlays on the links in Emacs

The cache folder sits next to the PDF:

./lectures/algo.pdf
./lectures/algo-slides/
  page-1.png
  page-4.png
  page-12.png

License

GPL-3.0-or-later