PDF TOC to Bookmarks
Extract table of contents from PDF pages and create clickable bookmarks using visual analysis and PyMuPDF.
When to Use This Skill
Use this skill when:
- User wants to add bookmarks to a PDF that lacks them
- PDF has printed TOC pages but no clickable navigation
- User mentions "bookmarks," "navigation," "TOC," or "table of contents" for PDFs
Workflow
1. Extract TOC Pages as Images
Extract TOC pages at high resolution for visual analysis:
from scripts.extract_toc_images import extract_toc_images
extract_toc_images(
pdf_path="/path/to/file.pdf",
toc_start_page=10, # First TOC page (1-based)
toc_end_page=16, # Last TOC page (1-based)
output_dir="/mnt/user-data/outputs/toc_images"
)2. Analyze Images Visually
Use Claude's vision capabilities to read TOC structure from images:
from view import view
# View each TOC image
view("/mnt/user-data/outputs/toc_images/page_010.png")
view("/mnt/user-data/outputs/toc_images/page_011.png")
# ... view all TOC pagesManually transcribe TOC structure into Python list format:
toc = [
[1, "Chapter 1: Introduction", 10],
[2, "1.1 Overview", 11],
[3, "1.1.1 Background", 12],
[2, "1.2 Methods", 15],
[1, "Chapter 2: Results", 20],
]Format: [level, title, printed_page_number]
level: Hierarchy depth (1=chapter, 2=section, 3=subsection)title: Exact text from TOCprinted_page_number: Page number as printed in book (not PDF page index)
3. Determine Page Offset
Calculate offset between printed page numbers and PDF page indices:
import fitz
doc = fitz.open("/path/to/file.pdf")
# Find a known page (e.g., where Chapter 1 starts)
# If book says "page 13" but it's PDF page 17, offset = 4
offset = actual_pdf_page - printed_page_numberCommon offsets: 0-10 pages (cover, copyright, preface typically not numbered)
4. Add Bookmarks to PDF
from scripts.add_bookmarks import add_bookmarks
add_bookmarks(
pdf_path="/path/to/input.pdf",
toc_list=toc,
page_offset=4, # Offset calculated above
output_path="/mnt/user-data/outputs/file_with_bookmarks.pdf"
)5. Verify and Deliver
Open output PDF in viewer to confirm bookmarks navigate correctly. Provide download link to user.
Critical Insights
Vision > Text Parsing: OCR/regex for TOC extraction is unreliable due to formatting variations. Visual analysis by Claude is faster and more accurate.
Page Offset: Always verify offset. Test by clicking a bookmark and checking if it lands on correct page.
Hierarchy Levels: Maintain consistent level numbering (1=chapter, 2=section, 3=subsection) for proper nesting in PDF viewer.
PyMuPDF Reference
import fitz
# Open PDF
doc = fitz.open("file.pdf")
# Extract page as image
page = doc[page_index] # 0-based
mat = fitz.Matrix(2.0, 2.0) # 2x zoom
pix = page.get_pixmap(matrix=mat)
pix.save("output.png")
# Set TOC (bookmarks)
toc = [
[1, "Chapter 1", 10], # level, title, page (1-based)
[2, "Section 1.1", 11],
]
doc.set_toc(toc)
# Save PDF
doc.save("output.pdf")
doc.close()Example Session
User: "Add bookmarks to this PDF based on the table of contents"
1. Extract TOC pages (10-16) as images
2. View images and transcribe TOC structure
3. Calculate page offset (e.g., 4 pages)
4. Create toc list with 182 entries
5. Add bookmarks using add_bookmarks script
6. Provide download link
Result: PDF with hierarchical bookmarks matching printed TOCTime Savings
- Traditional (regex/OCR): 30-60 min with errors
- Vision-based (this skill): 10-15 min with high accuracy