DEV Community: DesignClarity

The QA Script That Checks 8,556 PDF Links (and What It Caught)

DesignClarity — Sun, 27 Sep 2026 06:17:01 +0000

A link you never click is a bug your customer finds

I generated an 871-page hyperlinked PDF planner with Python — 8,556 internal link annotations across 730 daily pages, 105 weekly spreads, 24 monthly calendars, and a persistent tab bar. The render pass is only half the job. The other half is a verification script that re-opens the finished PDF and checks every single link, because a link you never click is a bug your customer finds.
This is the QA pass from the companion piece on generating the planner. Same build, second half of the story.

Check 1: the document opens and counts match

Before anything else, the script opens the built PDF and asserts the basics:

from pypdf import PdfReader
reader = PdfReader("planner-2026-2027.pdf")
assert len(reader.pages) == 871, f"expected 871 pages, got {len(reader.pages)}"

It also runs text extraction on a sample of page types — home, month, day, week, goal, notes — to confirm the document opens cleanly and the text layer is intact. A corrupted render fails here before wasting time on 8,556 links. Cheap check, run first.

Check 2: every link annotation resolves

This is the core loop. Every page's annotations are walked, every link-type annotation is resolved to its destination page, and anything pointing nowhere — or anywhere outside the document — is recorded:

broken = []
total = 0
for i, page in enumerate(reader.pages):
    for annot in page.get("/Annots", []):
        obj = annot.get_object()
        if obj.get("/Subtype") != "/Link":
            continue
        total += 1
        dest = obj.get("/Dest")
        page_idx = resolve_destination(reader, dest)
        if page_idx is None or not (0 <= page_idx < len(reader.pages)):
            broken.append((i, dest))
print(f"{total} links checked, {len(broken)} broken")

On the shipped build: 8,556 checked, 0 broken. The number is the whole point — a human spot-checking "a few links" on an 871-page document is theater. The script is the actual test.

Check 3: semantic spot-checks (not just "resolves")

A link can resolve to a valid page and still be wrong. March 14's calendar cell landing on March 15's page is a valid link and a broken product. So the script does semantic checks: extract text from the destination page and confirm it contains the expected date:

dest_page = reader.pages[resolved_idx]
text = dest_page.extract_text()
assert "March 14, 2026" in text, f"cell landed on wrong page: {text[:60]}"

Same treatment for the tab bar (each tab lands on its section's real first page) and for a sample of daily pages. Resolution checks catch crashes; semantic checks catch wrongness.

Check 4: the week chain

The 105 weekly spreads form a prev/next chain across two year boundaries — the highest-risk area for off-by-one errors. The script walks the full chain: week N's "next" link must land on week N+1's page, including the December 2026 → January 2027 handoff. First-week and last-week edge cases get explicit assertions. Calendar code loves to break at boundaries; the QA knows where to look.

Check 5: static-file guarantee

The finished file is asserted to be a static PDF: no JavaScript actions, no external URIs, no network calls. A planner that phones home is a support nightmare and a trust problem. The check is a few lines and it runs on every build.

What the script caught

Honest answer: on the shipped build it caught nothing — the QA result was PASS, 8,556/8,556, zero broken. The script earned its keep earlier in development, where the checks it now runs automatically are exactly the failure modes that bit during layout changes: named destinations are used instead of raw page numbers precisely because inserting a page during development used to silently repoint hundreds of links. The QA pass is the reason that class of bug can't ship again.

What the script can't check

The remaining gap is stated plainly in the product's own README: on-device testing in GoodNotes and Notability hasn't happened yet. pypdf says every link resolves; what it can't tell you is how a specific annotation app renders or handles 8,556 annotations on a real tablet. Desktop viewers forgive sins that annotation apps don't. That test is next, and the product copy doesn't claim it passed.

The takeaway

For template-style digital products, the QA script is part of the product. The render code makes the thing; the verify code is what lets you sell it with a straight face. Write the checks first, run them on every build, and disclose what they don't cover.

DesignClarity builds original digital products with code-first workflows. More of the factory's builds: https://designclarity.github.io

I Generated an 871-Page Hyperlinked PDF Planner With Python — 8,556 Links, Zero Broken

DesignClarity — Sun, 27 Sep 2026 05:35:22 +0000

The problem with digital planners

A hyperlinked PDF planner lives or dies on its links. Every monthly calendar date must jump to the right daily page. Every tab bar must land on the right section. Do it by hand in InDesign and you're placing thousands of link rectangles manually — and one fat-fingered destination ruins the product.

I generate mine with code instead. The latest build: 871 pages, 730 daily pages, 8,556 internal link annotations, verified zero broken. Here's the approach.

Architecture: render + verify as separate passes

Two passes, two libraries:

Render pass — draw every page and place every link annotation.
QA pass — re-open the finished PDF and mechanically verify every link resolves to a real page, plus semantic spot-checks (does the March 14 cell land on the March 14 page?).

Separating them matters. The render pass can have a systematic off-by-one that looks fine; only an independent verification pass catches it.

The core trick: date → page index math

Everything hangs off one function: given a date, which 0-based page index is its daily page? Once that's right, every calendar cell, week header, and tab bar is just arithmetic.

from datetime import date, timedelta
START = date(2026, 1, 1)
def daily_page_index(d: date, first_daily_page: int) -> int:
    """0-based PDF page index of this date's daily page."""
    return first_daily_page + (d - START).days

Layout plan (page indices decided up front, before drawing):

P_COVER = 0
P_HOME = 1
P_YEAR_2026 = 2
P_YEAR_2027 = 3
FIRST_MONTH_PAGE = 4            # 24 monthly spreads follow
FIRST_WEEK_PAGE = 4 + 24        # 105 weekly spreads follow
FIRST_DAILY_PAGE = 4 + 24 + 105 # 730 daily pages follow

Placing links: named destinations, not raw page numbers

In the real build I used named destinations (bookmarkPage + linkAbsolute) rather than raw page numbers, so inserting or removing a page during development never silently repoints hundreds of links. Named destinations are the single biggest robustness win: links survive layout edits.

# When drawing March 14, 2026's daily page:
c.bookmarkPage("daily-2026-03-14")
# When drawing the March 2026 calendar grid, over the "14" cell:
c.linkAbsolute("", "daily-2026-03-14", Rect=(x0, y0, x1, y1), thickness=0)

The tab bar: one function, every page

A persistent tab bar (Home / 2026 / 2027 / Months / Goals / Notes) appears on all 871 pages — one drawing function, six named-destination links, same coordinates everywhere. Six tabs × 871 pages = 5,226 of the 8,556 links come from this one function. Write it once, verify it once.

QA pass: trust nothing

The verification script re-opens the built PDF with pypdf and checks: (1) page count exactly 871; (2) every link annotation resolves — 8,556 checked, 0 broken; (3) semantic spot-checks — extract text from the destination page and confirm it contains the expected date; (4) week-chain integrity across all 105 weeks including year boundaries; (5) static-file check — no JavaScript, no external URIs, fully offline.

Practical notes

File size: 2.5 MB for 871 pages — vector drawing beats rasterized pages by an order of magnitude, and text stays selectable.
Page size: 768 × 1024 pt, portrait tablet-first, matches GoodNotes/Notability import expectations.
Fonts: stick to the 14 base PDF fonts or embed your own. A missing font on the buyer's device is a support ticket you can't debug remotely.
Test on-device. Desktop PDF viewers forgive sins that annotation apps don't. (Still on my own checklist — automated QA passed, device testing is next.)

Why generate instead of design?

Speed of iteration. Extending the planner from one year to two was a constant change and a re-run — not a month of manual layout. The QA script re-verified all 8,556 links in seconds. For template-style digital products, code is the design tool.

DesignClarity builds original digital products with code-first workflows. More of the factory's builds: https://designclarity.github.io