PDF page labels

The /PageLabels number tree in the document catalog, written directly, since pdf-lib has no high-level API for it. Nothing is drawn on any page. What changes is the label your reader shows in its page number box and beside its thumbnails, so page 3 can read iii or C instead.

Five: decimal, lower-roman, upper-roman, upper-alpha and lower-alpha, mapping to the PDF spec's D, r, R, A and a. Decimal is the default. There is no option for no label at all. Two runs are supported, so front matter and body carry different styles.

Yes. Click the page your body starts on and a second run begins there with its own style, first label and prefix. Front matter reads i, ii, iii while the body reads 1, 2, 3. Two runs is the limit: a scheme with three or more needs a full PDF editor.

It puts a fixed string in front of every label, so a prefix of Draft- with decimal style gives Draft-1, Draft-2 and so on. Leave it blank and no prefix entry is written into the file at all. It is stored once per run, not per page, and written as a PDF string so readers accept the tree.

Because it has to be a whole number of 1 or more, and it says so: "start must be a whole number of 1 or more". Zero and negative starts are refused because the PDF page label counter is defined as starting at one or higher. The start applies to the first page and the labels count up from there.

No. Nothing is added to the page content, so a printed sheet looks exactly as it did before. Labels live in the document structure and are for on-screen navigation. If you want numbers on the paper, use Add page numbers, which draws them at the bottom of each page.