BASALT · JOURNAL
Adding page numbers, headers, and footers to a PDF on a Mac
You have assembled a document from four sources and it needs consecutive page numbers before it goes out. macOS ships nothing that does this. Preview cannot number pages, and the close workarounds either place the number where a recipient can delete it or land it in the wrong corner on half the pages.
The job is geometry, not formatting
Placing a number sounds like a text operation. In practice almost all the difficulty is computing where "bottom center, half an inch up" actually is on a given page, because PDF pages do not agree on a coordinate frame.
The MediaBox origin is not always (0, 0). The specification allows any rectangle. [0 0 612 792] and [-12 -12 600 780] describe the same size in different frames, so a fixed offset from the origin lands differently on each.
The CropBox is what you see. When a page carries a CropBox smaller than its MediaBox, the visible page is the CropBox. Compute from the CropBox, falling back to the MediaBox, or footers drift off the visible area on cropped pages.
/Rotate rotates the rendering, not the coordinates. A page with /Rotate 90 displays sideways relative to its content coordinate system, so a footer at the bottom center of content space appears along a side edge, rotated, to the reader. Apply the inverse rotation to the text matrix.
Page sizes vary within one document. Assembled files mix letter, legal, A4, and scans of odd dimensions. Any position in absolute points rather than computed per page is right on some pages and wrong on others.
Get those four right and the rest is preference.
Content stream, not annotation
There are two places to put text on a page, and the difference decides whether the number survives.
An annotation is a separate object in the page's /Annots array. Any PDF editor deletes it in one action, its printing depends on the /Print bit in the annotation's /F flags field, and some pipelines strip annotations wholesale as review markup. A page number a tool can remove silently is not a page number.
The content stream is where the page's own text lives. A number written there is drawn by the same operators as the body copy and cannot be dragged off.
Two details make it behave like real text rather than a picture of one. Wrap the operators in q and Q so the number does not inherit a clipping path, a color, or a matrix left behind by the existing stream. And use a font resource with a ToUnicode mapping so the number extracts as text, letting a recipient search a page reference and land on the right page. Path outlines look identical and extract as nothing.
Numbering that does not match the page index
Real documents rarely start at one on the first page. A brief with a cover and a table of contents needs roman numerals on the front matter and arabic numbering restarting at the body. An exhibit compiled from four sources may need to continue the volume before it.
That reduces to two independent quantities: the page's physical index in the file, and the label printed on it. A tool offering only "number every page from one" cannot express those cases, while one accepting a starting value and a page range expresses all of them.
PDF also has a viewer-visible numbering scheme, held in the document catalog's /PageLabels number tree, which controls what the page navigation field displays. That is separate from anything drawn on the page, and setting one does not set the other.
Headers and footers are the same operation
A running header, a footer, a date line, and a Bates number are all text placed in a margin computed from the page's own box. Only the position and the string differ.
What separates a Bates number is what it must guarantee: uniqueness across a matter, a gapless sequence, and permanence through downstream handling, as covered in Bates numbering on a Mac.
Verifying the result
Numbering is easy to get almost right, and almost right is discovered by the recipient. The check is mechanical: extract the text of every page, pull the number from each, and assert the sequence advances with no repeats and no unintended gaps. That catches a mis-sorted source set, a restarted counter, and a page that silently received no stamp. Then print and look, because print flags and rotation behave differently on paper.
Where numbering sits in a workflow
Number before you redact. A privilege log references page numbers or Bates ranges, so marks placed on pages already carrying their permanent identifier make the log consistent with the production by construction. Number afterward and you have two passes whose agreement is assumed rather than enforced. The same argument runs through reproducible redaction.
Frequently asked questions
How do I add page numbers to a PDF on a Mac?
Use a PDF application that writes the number into each page's content stream and computes its position from that page's own CropBox and /Rotate value. macOS has no built-in page numbering: Preview cannot do it, and Automator's PDF actions handle assembly rather than stamping. A fixed offset in points is wrong on any document mixing page sizes.
Can Preview add page numbers to a PDF?
No. Preview has no page numbering feature, and its markup tools only place annotations, which are separate objects a recipient can delete and which print only when the annotation's print flag is set. Quartz filters operate on rendering rather than composing text, so they cannot do it either.
Why are my page numbers in the wrong corner on some pages?
Almost always a /Rotate value or a non-zero CropBox origin. /Rotate 90 turns the rendered page without turning the content coordinate system, so a footer placed at the bottom of content space appears along a side edge to the reader. Compute from the CropBox and apply the inverse rotation per page.
Can I start numbering at a page other than the first?
Yes, if your tool separates the page's physical index from the label printed on it. That separation is what lets you skip a cover page, restart numbering at the body, or continue a sequence from a preceding volume. A tool offering only numbering from one cannot express those cases.
Should page numbers be annotations or part of the page?
Part of the page, written into the content stream. An annotation is a separate object any editor deletes in one action, whose printing depends on a flag some tools leave clear, and that some pipelines strip wholesale as review markup. A content stream number prints unconditionally.
How do I add a header and footer to a PDF on a Mac?
The same way you add page numbers: place text in a margin computed from each page's own box, written into the content stream rather than as an annotation. Headers and footers differ only in position and in the string drawn, so a tool handling one handles the other. More detail is in adding a watermark that survives the print.
Will page numbers show up when the text is extracted?
Only if they are drawn as real text with a font resource and a ToUnicode mapping. A number rendered as path outlines or rasterized into an image looks identical on screen and extracts as nothing, so a recipient searching a page reference finds no match. Your verification pass depends on the same thing.
Do I number before or after redacting?
Before. A privilege log references page numbers or Bates ranges, so placing marks on pages that already carry their identifier makes the log consistent with the production by construction. Numbering afterward creates two passes whose agreement is assumed rather than enforced, and the redaction must then be checked for preserving the stamps.
Doing it in Basalt
Basalt's WATERMARK tool covers watermarks, headers, and footers, and its Bates numbering tool handles sequential identifiers across a production. Every tool writes a new file, so the original is never modified. Everything runs in a sealed engine process holding no network entitlement, enforced by macOS at the code-signature level, so documents never leave the Mac: no account, no telemetry, no cloud. These are two of 18 tools in one window, $29 once for up to three Macs, free for 24 hours, at basaltformac.com.
Redaction that proves itself
Basalt destroys the content you mark, then re-opens the file it wrote and proves the content is gone before it saves anything. Your documents never leave your Mac.