DEV Community: Marcus Hale

Your Generated PDFs Open Slowly in the Browser? They Are Probably Not Linearized

Marcus Hale — Wed, 14 Oct 2026 16:13:45 +0000

Your Generated PDFs Open Slowly in the Browser? They Are Probably Not Linearized

Last month a user emailed me about a report my little side project generates: "The PDF takes forever to show the first page. I thought it was broken."

The file was 4 MB. Not huge. But the in-browser preview sat on a spinner for several seconds before page one appeared, and on hotel Wi-Fi it was worse. The PDF itself was fine — it opened instantly in a desktop reader once fully downloaded. That was the clue: the browser could not render page one until it had downloaded essentially the whole file.

This post is the diagnosis and the fix, because if your app generates PDFs (invoices, reports, statements, tickets), your users are probably hitting the same thing.

The actual problem: byte order, not file size

A regular PDF is laid out for a writer, not a reader. The cross-reference table and page resources can sit anywhere in the file, objects for page one may be scattered from byte 0 to byte 4,000,000, and a viewer that wants to draw the first page has to go hunting — which, over HTTP, means range requests all over the file or just downloading everything.

Linearization (Adobe calls it "Fast Web View") restructures the file specifically for this:

Page one's objects are moved to the front of the file, in order.
A hint table up front tells the viewer exactly which byte ranges it needs for each page.
The viewer can then fetch just the first page's bytes with an HTTP range request and render immediately, pulling later pages on demand as the user scrolls.

Same content, same visual result, completely different first-paint behavior. The spec detail that matters: the file's first line carries a linearization marker in the header comment, and you can check for it:

# quick check: is this PDF linearized?
head -c 1024 report.pdf | grep -a "Linearized"
# or with qpdf, if you have it installed:
qpdf --check report.pdf | grep -i linearized

If those come back empty, your generated PDFs are not linearized — no matter what library produced them. Most generators (including the very common ones) do not linearize by default, because it is a second full pass over the file.

What I measured on my own file

Personal test, one file, throttled connection (Chrome DevTools "Slow 4G" profile), before and after linearizing the exact same generated report:

	Before	After linearization
File size	4.1 MB	4.2 MB (slightly larger — hint tables cost bytes)
Bytes needed to render page 1	~4.1 MB (effectively all of it)	~180 KB
Time to first page on screen	~3.5 s	under 0.5 s

Two things worth noting from that table. First, the linearized file got marginally bigger, and that is normal — you are trading a few percent of size for page-at-a-time delivery. Second, the win is not "the file loads faster"; it is "the first page renders after ~4% of the bytes." On a fast office connection nobody noticed the problem. On the connections your users actually complain from, it is the whole experience.

Your numbers will differ — this was my file, my hosting, my throttle profile — but the mechanism is deterministic: if page one needs the whole file, slow networks will feel it linearly.

The fix, at three levels

Level 1 — your generator. Some toolchains can emit linearized output directly or via a post-processing flag. If yours can, turn it on in the generation pipeline and be done. The post-processing step in pseudo-code is trivial; the cost is one extra pass per file:

generate report.pdf
linearize report.pdf -> report-web.pdf
serve report-web.pdf (with a server that honors Range requests)

Level 2 — your server. Linearization only pays off if your hosting actually answers HTTP Range requests with 206 Partial Content. Most static hosts and CDNs do. Check yours:

curl -sI -H "Range: bytes=0-1023" https://your-host/report.pdf \
  | grep -iE "HTTP/|accept-ranges|content-range"

If you see 200 instead of 206, the browser will fall back to downloading everything and the linearization buys you almost nothing. Fix the serving layer first.

Level 3 — one-off files. For PDFs that already exist (a backlog of generated reports, files clients send you, anything not flowing through your pipeline), you just need a linearizer. I used the one in PDFLean — the dedicated tool page is pdflean.com/tools/pdf-linearize — dropped the original report in, downloaded the processed copy, and verified it with the head/grep check above before swapping it into my test. For a one-off fix or a sanity check before you automate anything, that is the fastest path: process, verify the marker is there, re-measure.

The checklist I now run for generated PDFs

Generate a sample with production-like data (empty test files hide this — you need real length).
Check the linearization marker (command above).
Confirm the host returns 206 for a range request.
Throttle the connection and time first-page render, not full download.
Only then argue about compression — size and structure are separate problems, and structure is the one that blocks first paint.

That user who emailed me never wrote back, which in support terms is the best possible outcome. The report did not get smaller or prettier. It just stopped making people wait for page one.

The PDF Review Loop That Finally Stopped Eating My Afternoons

Marcus Hale — Wed, 14 Oct 2026 08:00:40 +0000

Most of the contract work I do for clients ends the same way: a PDF goes out, and a PDF comes back covered in comments. Highlights with no note attached. A sticky note that just says “fix this?” on page 9. Three people commenting on three different versions, because the file in the email thread is never the file in the shared drive.

The tools were never the problem. The problem was that “review” had no rules, so every round produced a new pile of comments I had to archaeology my way through. Here’s the loop I run now. It’s half conventions, half a small script, and it cut my review rounds from four-ish to usually two.

Rule 1: One marked copy, named like it means it

There is exactly one file that accepts comments: contract_CLIENT_review.pdf. Not v7, not final-FINAL, not the one attached to the third reply in the thread. When a new round starts, I archive the previous marked copy as contract_CLIENT_review_r1.pdf and the working name stays the same.

This sounds trivial and it eliminated the single biggest time sink: merging comments from parallel versions. If someone sends me comments on a different file, those comments don’t exist until they’re redone on the one marked copy. People adapt to this rule in about one round, because redoing comments is more annoying than following it.

Rule 2: Three annotation types, three meanings

I ask reviewers to use only three things, each with a fixed meaning:

Highlight + note = a question. (“Is this the rate we agreed in March?”) Questions get answered in a reply note, not by silently editing the text.
Strikethrough with replacement text = a proposed edit. If you want a clause changed, strike it and type the replacement. No “maybe soften this paragraph somehow” — that’s a question, use a highlight.
Sticky note starting with DECISION: = something already settled that I should just apply. (“DECISION: payment terms are net 30, confirmed with their finance lead.”)

Every other annotation type — the arrows, the drawing tools, the lone carets with nothing attached — gets ignored, and reviewers know it gets ignored. The constraint feels strict for about ten minutes. Then people realize their comments actually get read, in order, and addressed.

Most of my clients annotate in whatever’s open on their machine. The ones without Acrobat use the annotate tool in PDFLean in a browser tab, which covers exactly these three types and nothing else — honestly the limited palette is part of why it works. A reviewer with fourteen annotation tools will use all fourteen.

Rule 3: The script turns comments into a checklist

Before I touch the document, I extract every annotation into a plain list with page numbers:

import fitz  # PyMuPDF

def dump_annots(path):
    doc = fitz.open(path)
    for page in doc:
        for a in page.annots():
            info = a.info
            yield {
                "page": page.number + 1,
                "type": a.type[1],           # Highlight, StrikeOut, FreeText, ...
                "author": info.get("title", ""),
                "note": (info.get("content") or "").strip(),
            }

for row in dump_annots("contract_CLIENT_review.pdf"):
    print(f'p{row["page"]:>2} [{row["type"]:<9}] {row["author"]}: {row["note"]}')

That printout becomes the round’s checklist. Every line gets one of three marks as I work: applied, answered, or pushed back with a reason. At the end of the round, the marked-up checklist goes back to the client with the new draft. Half the value is the checklist itself — reviewers can see their DECISION notes were applied and their questions got answers instead of vanishing into a fresh PDF. The other half is selfish: two rounds later, when someone asks “why does clause 6 say net 30?”, the answer is in a text file, not buried in a dead PDF’s comment layer.

One gotcha: some tools store the visible note text in the annotation’s popup rather than its content field, so occasionally the script prints an empty note for an annotation that visibly has text. When the checklist shows a blank, I open that page and read the popup directly. It happens rarely enough that I haven’t bothered automating around it.

Rule 4: What ships is flat and clean

When a round closes, two files leave my machine:

The new working draft (still commentable, still the same filename pattern).
When the document is final: a flattened copy. Flattening bakes the annotations into the page content — or, for the truly final version, I produce a clean copy with no annotations at all and archive the last marked copy with its checklist.

The distinction matters. A flattened file is for records and signatures: nobody’s comment layer should be editable in the archived version of a signed agreement. The marked copy plus checklist is the audit trail; the flat file is the artifact. Mixing those two jobs into one file is how you end up, months later, unable to prove which comments were ever addressed.

What this doesn’t fix

It doesn’t make reviewers respond faster, and it doesn’t rescue a document that was badly structured before review started — comments cluster on the confusing parts either way, which is its own kind of useful signal. What it does is make each round terminal: every comment enters as a question, an edit, or a decision, gets extracted into a list, and leaves a written trace. Review stops being a recurring meeting with a PDF and becomes a queue that empties.

If your current process is “send PDF, receive vibes,” steal the parts in order: one marked copy first, the three-type rule second, the extraction script third. The first one alone is worth more than the other two combined.

Batch-Converting 60 Receipt Photos into One PDF (and Back Again)

Marcus Hale — Wed, 14 Oct 2026 02:47:22 +0000

A client of mine documents site work with a phone. Every Friday I get a folder -- sometimes a literal zip over email -- with 40 to 80 photos: receipts, signed delivery notes, whiteboard shots, the occasional crooked picture of a screen. My job is to turn that into one PDF the bookkeeper can file, in capture order, without spending my afternoon in a file dialog.

This is the batch image workflow I landed on. It has two directions, because the reverse job shows up just as often: a PDF arrives and somebody needs the images out of it, one file per image, right now.

Direction 1: Many images, one PDF

The scripting route takes about fifteen lines with Pillow:

from PIL import Image
from pathlib import Path

photos = sorted(Path("site-photos").glob("*.jpg"))
pages = []
for p in photos:
    img = Image.open(p).convert("RGB")
    img.thumbnail((1654, 2339))          # ~A4 at 200 DPI, plenty for receipts
    pages.append(img)

pages[0].save(
    "site-week-41.pdf",
    save_all=True,
    append_images=pages[1:],
    resolution=200.0,
)

Three details that matter more than the code:

Sort order is the document. Phone filenames (IMG_2041.jpg) sort fine until someone AirDrops from a second phone and the names interleave wrong. If order matters -- and for receipts it does -- rename by timestamp first (exiftool "-FileName<DateTimeOriginal" does it in one pass) or sort by modification time and eyeball the first and last page before sending.
Downscale before you bind. A 48MP phone photo at full size makes a 200MB PDF nobody can email. 200 DPI at A4-ish dimensions is more than legible for a receipt and cuts the file by an order of magnitude.
.convert("RGB") is not optional. One PNG with an alpha channel or one HEIC-converted CMYK JPEG will kill the whole save at page 37. Ask me how I know.

Direction 2: One PDF, many images

Extracting with PyMuPDF gets you the embedded images at their stored resolution, which is what you want for re-use:

import fitz  # PyMuPDF

doc = fitz.open("catalog.pdf")
for page_no, page in enumerate(doc):
    for i, img in enumerate(page.get_images(full=True)):
        xref = img[0]
        pix = fitz.Pixmap(doc, xref)
        if pix.n > 4:                    # CMYK etc.
            pix = fitz.Pixmap(fitz.csRGB, pix)
        pix.save(f"p{page_no + 1:02d}_{i + 1}.png")

Know what you're getting: this pulls the raw image objects. If the "image" on a page is actually a rendered chart or a scanned page assembled from tiles, you'll get tiles and charts, not the screenshot you were imagining. For a full-page render instead, page.get_pixmap(dpi=200) is the honest tool -- different job, different output.

Where I stop scripting

I keep the scripts for the Friday folder, because it arrives in the same shape every week. For the one-off jobs -- a client sends three PNGs and wants one PDF back now, or I need a quick batch conversion on a machine where I haven't set anything up -- I use the image batch tool on PDFLean in the browser instead of touching a terminal. Same operations, drag, drop, done. Files I process there without an account are deleted immediately after processing, which is the property I check first whenever a client's documents are involved; a free account raises the per-file limit to 50MB for the weeks the photos arrive huge.

The rule of thumb after a year of this: if the job repeats weekly in the same shape, script it once and never think again. If it happens twice a quarter, a batch tool in the browser is faster than finding the script, remembering its arguments, and updating it because Pillow changed something. Both directions live in my runbook now -- the expensive version of this task was always doing it one file at a time.

How I Batch-Stamp and Rename 40 Invoices in One Go

Marcus Hale — Tue, 13 Oct 2026 23:02:22 +0000

Every month, my clients' suppliers send me a folder's worth of invoices as PDFs. The filenames are chaos: INV_final2.pdf, scan0003.pdf, document (1).pdf. Before any of them can go to the bookkeeper, each one needs two things: a "RECEIVED" stamp with the date, and a filename a human can search later — my pattern is YYYY-MM-DD_vendor_total.pdf.

Doing this by hand for ~40 files took me about an hour of opening, stamping, saving, renaming. Now the mechanical part is a script, and my job is a 10-minute review pass. Here's the setup, including the parts that broke.

The pipeline

Three folders: inbox/ (originals, never touched), work/ (script output), review/ (files the script couldn't handle, which I fix manually). The rule that saves me monthly: the script only reads from inbox/ and only writes to work/. No in-place edits, ever. If a run goes wrong, delete work/ and re-run.

Step 1: Extract the data from the text layer

Most invoices are born-digital PDFs, so the vendor name, date, and total are sitting in the text layer. I pull them with pdfplumber and a couple of regexes:

import re, pdfplumber

def extract(path):
    with pdfplumber.open(path) as pdf:
        text = "\n".join(p.extract_text() or "" for p in pdf.pages)
    total = re.search(r"Total due[:\s]*\$?\s*([\d,]+\.\d{2})", text, re.I)
    date  = re.search(r"(\d{4})-(\d{2})-(\d{2})", text)
    return {
        "total": total.group(1).replace(",", "") if total else None,
        "date": date.group(0) if date else None,
        "text": text,
    }

Vendor names come from a small lookup dict I maintain ({"ACME LOGISTICS": "acme-logistics", ...}) matched against the first lines of text. New supplier? The script doesn't guess — it flags the file for review/ and I add one line to the dict. That dict is boring and it's the most valuable part of the whole system.

Step 2: Build the stamp as its own tiny PDF

Don't draw the stamp into the invoice with a graphics library page by page — generate one transparent stamp PDF (RECEIVED 2026-10-05, red, slightly rotated) and reuse it as an overlay:

# stamp.py — run once per month with the received date
from reportlab.pdfgen import canvas
from reportlab.lib.colors import HexColor

c = canvas.Canvas("stamp.pdf", pagesize=(220, 60))
c.setStrokeColor(HexColor("#C0392B")); c.setFillColor(HexColor("#C0392B"))
c.setLineWidth(2); c.rect(4, 4, 212, 52)
c.setFont("Helvetica-Bold", 15)
c.drawCentredString(110, 36, "RECEIVED")
c.setFont("Helvetica", 11)
c.drawCentredString(110, 18, "2026-10-05")
c.save()

Step 3: Overlay and rename with pikepdf

from pikepdf import Pdf, Rectangle

stamp = Pdf.open("stamp.pdf").pages[0]
with Pdf.open(src) as pdf:
    page = pdf.pages[0]
    page.add_overlay(stamp, Rectangle(380, 730, 600, 790))
    pdf.save(dst)  # dst = work/2026-10-02_acme-logistics_1240.00.pdf

Placement is a Rectangle in the top-right of page 1 only — that's where every supplier leaves white space, and stamping all pages was overkill for an internal processing mark. (This is a bookkeeping stamp, not a legal one; anything that needs an audit trail gets handled in the accounting system, not burned into the PDF.)

Where it breaks — the review folder is the point

Roughly a quarter of my invoices are scans: flat images, no text layer, the extractor returns nothing. Early on I tried to make the script "smart" about these. That was a mistake — silent misreads are worse than no reads. Now anything without a usable text layer, a missing total, or an unknown vendor goes straight to review/ untouched.

For the scans I run one OCR pass — I use PDFLean's OCR tool for this, since the files are already leaving my machine nowhere else that month — then drop the OCR'd copies back into inbox/ and re-run the script. On a typical month that's 8–10 files, and the second pass usually clears all but one or two genuinely mangled scans (skewed, stamped over the total by the supplier's own stamp, that kind of thing). Those last ones I name by hand. It's fine. A workflow that handles 38 of 40 and clearly shows you the other 2 beats a workflow that "handles" all 40 and hides its guesses.

Other failure modes worth knowing:

Locale formats. A European supplier writes 1.240,00. My regex reads that as 1.240. The review pass catches it because the renamed total looks absurd against the invoice count — but only because I eyeball the list before sending. Keep the review pass.
Credit notes have negative totals and the word "Total" next to a positive number. I filename them with a -credit suffix by hand; automating that distinction wasn't worth it.
Duplicate submissions. Same invoice sent twice by two people at the client. Identical file size + identical total is my cheap dedupe signal in the summary printout.

The part I didn't automate

The script ends by printing a summary: filename, vendor, total, one line per invoice. I read that list against the bank feed before anything goes to the bookkeeper. That's the 10 minutes. Everything before it — the opening, stamping, saving, renaming — was never judgment work, it was just slow. That's the line I try to draw in all my document workflows: automate the mechanical pass completely, and make the exceptions louder, not quieter.

Full script (minus my vendor dict) is about 120 lines. The monthly cost of running it is zero and one coffee, most of which I spend reading the summary anyway.