add_text

Add user-specified text strings to PDF pages

Usage

pdftl <input> add_text <spec>... output <file> [<option>...]

Details

Add user-specified text strings to PDF pages.

Note: This operation requires the ‘reportlab’ library. If not installed, run: pip install pdftl[add_text].

A text specification (<spec>) has the format:

[page range]<delimiter><text string><delimiter>[<options>]

<delimiter> must be a single, non-alphanumeric character (e.g., /, !, #).

Dynamic Text Variables in text strings

The <text string> supports variable substitution using curly braces {}, in one of the following formats.

1. Simple format: e.g., {page} gives the current page number. Possible variables are:

   • page: The current page number (1-based index).

   • n: The sequence number (1-based index within the current spec)

   • total: The total number of pages in the PDF.

   • filename: The name of the input PDF file, including the extension (e.g., “document.pdf”).

   • filename_base: The base name of the input PDF file, without the extension (e.g., “document”).

   • filepath: The full path to the input PDF file.

   • date: The current date formatted as YYYY-MM-DD (e.g., 2025-12-12).

   • time: The current time formatted as HH:MM:SS (e.g., 13:53:41).

   • datetime: The current date and time in ISO 8601 format (e.g., 2025-12-12T13:53:41.123456).

2. Source Metadata (Pipeline): These variables track the original source file of a page, even after operations like cat or shuffle.

   • source_filename: The filename of the specific source PDF this page came from.

   • source_path: The full file path of the source PDF.

   • source_page: The original page number in the source file.

   • source_rotation: The rotation of the source page (0, 90, 180, 270).

   • source_width / source_height: The dimensions of the source page.

   • source_orientation: “Portrait” or “Landscape”.

3. Arithmetic & Formatting: Support for offsets and Python-style padding. Useful for Bates stamping.

   • Offset: {page+100} starts numbering at 101.

   • Padding: {page:06d} produces “000001”.

   • Combined: {page+5000:06d} produces “005001”.

4. Complex: e.g., {total-page} gives the number of pages remaining. (for now, this is the only complex possibility).

5. Metadata: e.g., {meta:Title}. The metadata variables allow you to insert information stored within the PDF document’s own metadata dictionary (/Title, /Author, etc.) into your text.

The format for a metadata variable is: {meta:<KeyName>} where <KeyName> is the exact, case-sensitive key found in the PDF’s document information dictionary (it corresponds to the PDF keys like /Title after the leading slash is stripped).

The available keys are determined by the contents of the PDF itself, but common examples derived from the PDF specification include: Title, Author, Subject, Keywords, Creator, Producer, CreationDate. If the specified <KeyName> does not exist in the PDF’s metadata, the variable will be substituted with an empty string.

6. Escaping: {{...}} renders a literal {...} string.

Hyperlinks

You can create clickable hyperlinks within your text using standard Markdown syntax: [Display Text](URL). Dynamic variables are supported in both the display text and the URL.

Example: [Visit Page {page}](https://example.com/p{page}) Escaping: Use \[ and \] if you need literal brackets inside the text.

Options

Options are passed as comma-separated key=value pairs inside parentheses, e.g., (position=bottom-center, size=10).

Positioning and layout options

position=<keyword>: Preset position (top-left, center, mid-center, bottom-right, etc.). Cannot be used with x/y.

x=<dim>, y=<dim>: Absolute coordinates.

offset-x=<dim>, offset-y=<dim>: Offset relative to the main position.

Dimension values (<dim>) must include a unit (e.g., 10pt, 5cm, 20%) or default to points (pt). Supported units are pt, in, cm, mm, and %.

rotate=<float>: Angle in degrees (e.g., 45).

Formatting options

font=<string>: Font name (e.g., Helvetica-Bold).

size=<float>: Font size in points.

color=<string>: Text color. 1, 3, or 4 space-separated numbers between 0 and 1. Examples: 0.5 is gray, 1 0 0 is red, and 1 0 0 .5 is semi-transparent red.

bgcolor=<string>: Background color. 1, 3, or 4 space-separated numbers between 0 and 1.

padding=<dim>: Padding for background colored rectangle, if present

linkcolor=<string>: Color for hyperlinks (uses the same format as color). Defaults to the main color if not set.

align=<'left'|'center'|'right'>: Horizontal alignment.

Examples

Add “Page X of Y” to the bottom-center of all pages

pdftl in.pdf add_text '1-end/Page {page} of {total}/(position=bottom-center, size=10, offset-y=10pt)' output out.pdf

Add a large, rotated “DRAFT” watermark to odd pages

pdftl in.pdf add_text 'odd!DRAFT!(position=mid-center, font=Helvetica-Bold, size=72, rotate=45, color=0.8 0.8 0.8)' output out.pdf

Add a header with the document’s title to page 1

pdftl in.pdf add_text '1/Document: {meta:Title}/(x=1cm,y=28cm,font=Times-Bold,size=14)' output out.pdf

Stamp pages with their original filename (useful in pipelines)

pdftl A.pdf B.pdf cat --- add_text '1-end/Source: {source_filename} (p.{source_page})/(position=bottom-left, size=8)' output out.pdf

Apply a Bates stamp (starting at DEF-005001) to the bottom-right

pdftl in.pdf add_text '/DEF-{page+5000:06d}/(position=bottom-right, size=10, color=1 0 0)' output out.pdf

Add a clickable Markdown link with a custom link color

pdftl in.pdf add_text '/Visit [Our Website](https://example.com)/(position=top-right, size=12, linkcolor=0 0 1)' output out.pdf

Apply sequential sequence numbering that resets per specification

pdftl in.pdf add_text '1-3/Exhibit A-{n}/(position=top-left, size=10)' '4-6/Exhibit B-{n}/(position=top-left, size=10)' output out.pdf

Tags: in_place, text

Source: pdftl.operations.add_text

Read online: https://pdftl.readthedocs.io/en/stable/operations/add_text.html

Type: Operation