← All guides

Check every link and bookmark in a PDF

A big manual gets hyperlinked once, then edited forever: pages move, chapters vanish, external sites die. Nobody clicks all 1200 links again. links does, in seconds, and names exactly what's broken and where.

How to do it

pip install pdfblah

pdfblah links manual.pdf

internal links: 214 ok, 2 broken
  page 41: named destination 'sec-9-3' does not exist
  page 108: destination page is not in the document
bookmarks: 30 ok, 1 broken
  'Appendix D': named destination 'app-d' does not exist
external URLs: 12 ok, 1 broken, 1 unreachable
  https://example.com/spec-v1 (page 3): HTTP 404

What gets checked, and how honestly

• Internal jumps and bookmarks are resolved against the pages that actually exist, through named destinations too, so a link that points at a deleted chapter is caught, not just malformed ones.
• External URLs get three verdicts: ok, broken (the server answered 4xx/5xx), and unreachable (no answer; maybe you're offline, maybe the site is gone). No lumping the last two together.
• --offline runs the structural check alone and simply counts the URLs it didn't contact.
• Exit code 1 when anything is broken, so it slots into CI: generate your manual, then let the link check gate the release.

Tips

• Run it before every release of a linked document; it costs seconds and rot is silent.
• Merging PDFs is where internal links usually die; check the combined file, not the sources.
• --json gives the full machine-readable report for scripts.