Pagecraft

page-numbers

Add page numbers

Number the pages, in any of nine positions and any of five notations.

Reads
a PDF — application/pdf
Writes
one file — PDFs
Tool page
/add-page-numbers

Example

Number a bundle that was assembled out of four separate files.

Given

  • bundle.pdf — an ordinary PDF of 5 pages

From code

            import { loadDocument, runOperation } from '@pagecraft/core';

const bundle = await loadDocument({ bytes, name: 'bundle.pdf' });

const [output] = await runOperation('page-numbers', [bundle], {
  template: 'Page {n} of {total}',
});

From a shell

            pagecraft page-numbers bundle.pdf --template 'Page {n} of {total}'

What comes back

One PDF of 5 pages, containing “Page 1 of 5”.

This example is run by the test suite. If it stopped being true, the build would fail.

Options

template--template

string

What each number says

The number goes where {n} is. Also understood: {n}, {total}, {filename}, {date}.

Default: 'Page {n} of {total}'

format--format

string, one of

Counting in

Default: 'arabic'

  • arabic — 1, 2, 3.
  • roman — i, ii, iii.
  • roman-upper — I, II, III.
  • alpha — a, b, c.
  • alpha-upper — A, B, C.

start--start

integer

Starting at

The number the first numbered page carries.

Default: 1

pages--pages

string, a page selection: '1-3, 7, 9-', 'even', 'last'

Pages

Which pages carry a number. Counting starts at the first of them.

Default: 'all'

position--position

string, one of

Position

Default: 'bottom-center'

  • top-left — Top left
  • top-center — Top centre
  • top-right — Top right
  • middle-left — Middle left
  • middle-center — Centre
  • middle-right — Middle right
  • bottom-left — Bottom left
  • bottom-center — Bottom centre
  • bottom-right — Bottom right

margin--margin

number

Margin

Default: 10

unit--unit

string, one of

Measured in

Default: 'mm'

  • mm — Millimetres
  • cm — Centimetres
  • in — Inches
  • pt — Points

font--font

string, one of

Typeface

Default: 'sans'

  • sans — Helvetica.
  • serif — Times.
  • mono — Courier.

bold--bold

boolean

Bold

Default: false

italic--italic

boolean

Italic

Default: false

fontFile--font-file

Uint8Array

Font file

A TrueType or OpenType font to set the text in. Needed for scripts the built-in fonts do not cover, unless the host supplies one.

size--size

number (pt)

Size

Default: 10

color--color

string, '#rrggbb'

Colour

Default: '#000000'

What it cannot do

  • The number is drawn on top of the page, so a page whose content already reaches the edge is written over rather than reflowed.
  • Shaping and joining come from the font itself, and nothing reorders a line: text is drawn in the order it is given, so a line mixing right-to-left and left-to-right writing comes out in that order rather than in reading order.