How the numbers are placed
A PDF page has more than one size. The MediaBox is the full sheet, an optional CropBox is the part a viewer shows, and a page can be stored sideways with a rotation that viewers undo. A number placed by the file's own coordinates would land in the wrong corner of such a page, or sideways. This tool works out the corner on the page as a reader sees it: it takes the visible area, applies the rotation, places the number there, and turns it back into the page's own coordinates, so the number reads upright whatever the page is.
The margin is the distance from the page edge to the nearest edge of the number's text. Every page is measured on its own, so a file that mixes sizes gets the number at the same distance from the edge on each page. For double sided printing, Mirror on even pages puts the number on the outer edge of every spread: with the number at the bottom right, even pages get it at the bottom left.
The number is drawn on top of what is already there. If a page has something in that margin, such as a printed footer or the dark border of a scan, the number lands on it. Choose another spot or a bigger margin. The preview uses the same calculation as the saved file and warns when a number would run off a page.
Formats, roman numerals and covers
The ready made formats are 1, Page 1, Page 1 of 12, 1 / 12 and - 1 - (written with ordinary hyphens). Choose Your own text for something else, such as Seite {n} von {N}. {n} stands for the page's number and {N} for the number of the last page. The standard PDF fonts cover Western European letters, so é, ü, ñ and € work, while Greek, Cyrillic, Arabic, Hebrew and Asian scripts do not. The tool says so instead of writing a wrong character.
Roman numerals exist for 1 to 3999, in lower case (i, ii, iii) or upper case (I, II, III), and they apply to the total too: Page iv of xii. A number above 3999 is written with digits.
To leave a cover without a number, set Skip first to 1. Then choose how to count. Start at 1 gives the first numbered page the start number, so the second page of the file is page 1. Keep real numbers gives every page the number its place gives it, so the second page is page 2. With Page 1 of N, N is the number of the last page in that counting, which is why a 12 page file with a 2 page cover that is counted again says of 10.
Odd, even and ranges always refer to the page numbers you see in a viewer, so odd means pages 1, 3, 5 and so on.
What changes in the file, and what does not
The numbers are real text, not pictures: they can be selected, searched and read aloud. They are marked as a header or footer of the page (a pagination artifact), as word processors mark them, so screen readers skip them and a tagged PDF stays correctly tagged.
Pages, fonts, images, forms, links, bookmarks and the document information are copied as they are. What changes is how the file is written. The PDF library writes the whole file again, so it is saved as PDF 1.7, a "fast web view" arrangement is lost (the file still opens normally), and a digital signature stops being valid, as it does with any edit. The size barely moves: a number adds about 200 bytes a page (measured on test files), and files made by programs that do not pack their objects often come out smaller.
A viewer's own page counter, such as 3 of 12, comes from the file's structure and is not changed by this tool, so it still counts every page, covers included.
Checking the result
After saving, the tool opens the new file again and reads the text of the numbered pages to find each number on its page. On a long file it reads a spread of pages, from the first to the last, and says how many it looked at. This catches a missing number. It cannot tell how the number looks on top of a busy page, which is what the preview is for.