pdf-destinator 0.1.0

Interactive GUI tool to add named destinations and clickable links to PDF files

PDF Destinator

An interactive GUI tool to add named destinations and clickable link regions to PDF files - without expensive software like Adobe Acrobat.

Features

• Visual PDF navigation with zoom and page controls
• Click to set destination positions for internal navigation
• Drag to create link regions pointing to destinations or external URLs
• Load/save destinations - preserves existing destinations in PDF
• Hover-to-delete link regions with visual feedback
• Mouse wheel scrolling with automatic page changes at boundaries
• Keyboard shortcuts for efficient workflow
• JSON configuration support for batch workflows
• Diagnose mode to inspect existing PDF structure

Installation

pip install pdf-destinator

System Requirements

• Python 3.8+
• tkinter (usually included with Python)

On Linux, you may need to install tkinter separately:

sudo apt-get install python3-tk  # Debian/Ubuntu
sudo dnf install python3-tkinter  # Fedora

On macOS:

brew install python-tk

Usage

Basic Usage

Open a PDF and add destinations interactively:

pdf-destinator document.pdf

With Pre-defined Titles

Pre-populate the destination list with titles:

pdf-destinator document.pdf --titles "Introduction" "Chapter 1" "Chapter 2" "Conclusion"

With JSON Configuration

Load destinations from a JSON file:

pdf-destinator document.pdf --json destinations.json

JSON format:

[
  {
    "pdfFile": "document.pdf",
    "destinations": [
      { "id": "intro", "title": "Introduction" },
      { "id": "chapter-1", "title": "Chapter 1" },
      { "id": "https://example.com", "title": "External Link", "type": "url" }
    ]
  }
]

Diagnose Mode

Inspect existing destinations and links in a PDF:

pdf-destinator document.pdf --diagnose

Workflow

1. Open PDF - Run pdf-destinator with your PDF file
2. Navigate - Use arrow keys or buttons to browse pages
3. Click - Click on the page to set a destination position
4. Drag - Drag a rectangle to create a clickable link region
5. Delete - Hover over a link region (cursor changes to X) and click to delete
6. Save - Click "Save and quit" when done

Keyboard Shortcuts

Key	Action
Left/Right	Navigate pages
Up/Down	Navigate destinations
Mouse wheel	Scroll page (changes pages at boundaries)

Mouse Actions

Action	Result
Click	Set destination position at click location
Drag	Create link region pointing to current destination
Hover + Click on link	Delete the link region

Status Indicators

In the destination list:

• [x] - Destination has a position set
• [o] - Destination exists in PDF (loaded)
• [ ] - Destination needs a position
• [URL] - External URL (no position needed)

Use Cases

• Create table of contents links in newsletters or reports
• Add navigation to long PDF documents
• Link external resources from PDF pages
• Fix or update existing PDF destinations
• Batch processing with JSON configuration

Python API

You can also use pdf-destinator programmatically:

from pdf_destinator import PDFDestinationPicker

destinations = [
    {"id": "intro", "title": "Introduction"},
    {"id": "chapter-1", "title": "Chapter 1"},
]

app = PDFDestinationPicker("document.pdf", destinations)
app.run()

Dependencies

• PyMuPDF - PDF rendering and link annotations
• pypdf - Named destinations
• Pillow - Image processing for display

License

MIT License - see LICENSE file.

Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

Acknowledgments

Created with the help of Claude (Anthropic) as a free alternative to expensive PDF editing tools.