Pagecraft

header-footer

Headers and footers

Add a running head or foot in any of six slots, with the filename, date and page.

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

Example

Put the client name and the page number on every page of a report.

Given

  • report.pdf — an ordinary PDF of 4 pages

From code

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

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

const [output] = await runOperation('header-footer', [report], {
  headerLeft: 'Acme Ltd',
  footerRight: '{n} / {total}',
});

From a shell

            pagecraft header-footer report.pdf --header-left 'Acme Ltd' --footer-right '{n} / {total}'

What comes back

One PDF of 4 pages, containing “Acme Ltd”.

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

Options

headerLeft--header-left

string

Header, left

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

headerCenter--header-center

string

Header, centre

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

headerRight--header-right

string

Header, right

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

footerLeft--footer-left

string

Footer, left

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

footerCenter--footer-center

string

Footer, centre

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

footerRight--footer-right

string

Footer, right

Left empty, nothing is drawn there. Understood: {n}, {total}, {filename}, {date}.

Default: ''

date--date

string

Date

What {date} says. Left empty, it is today, written as 2026-08-25.

Default: ''

start--start

integer

First page is number

What {n} says on the first page of the document, headed or not.

Default: 1

pages--pages

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

Pages

Which pages carry the head. The numbering still counts them all.

Default: 'all'

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: 9

color--color

string, '#rrggbb'

Colour

Default: '#000000'

What it cannot do

  • The head is drawn on top of the page, so a page whose own content already reaches into the margin is written over rather than reflowed.
  • A slot that is too long for the page runs past the edge; nothing is shortened or wrapped for you.
  • 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.