Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

Merging PDFs for print

merge takes existing PDFs and returns one PDF made for printing: several contracts from different tools, sent to the printer as one file. It takes the files as bytes, each with its name, and returns the merged file. Nothing is laid out. Each page is drawn as it looked, at its own size, and what is not on the printed page is left behind: forms, links and bookmarks are gone, and the file keeps the look of the pages.

It is not a way to edit or read PDFs. The merged file is for the printer, not for the screen, where the originals are the better copy.

Give merge the files in the order they are to print. Each is a name, which every error about it uses, and the file’s bytes.

import { readFile, writeFile } from 'node:fs/promises'
import { L } from '@lpdfio/lpdf'
const engine = L.engine()
const merged = await engine.merge([
{ name: 'contract-a.pdf', pdf: await readFile('contract-a.pdf') },
{ name: 'contract-b.pdf', pdf: await readFile('contract-b.pdf') },
{ name: 'contract-c.pdf', pdf: await readFile('contract-c.pdf') },
], { doubleSided: true })
await writeFile('contracts-to-print.pdf', merged)

merge blocks as render does: in JavaScript it returns a promise and runs on the render worker, with the engine’s timeout and maxMemoryMb; in Python, Java, C# and PHP it returns the bytes on the calling thread. One call takes 1,000 files at most.

The names are written in each language’s case: allowSigned in JavaScript and PHP, allow_signed in Python, AllowSigned in C#, and allowSigned(…) in Java. The options argument is optional, and each option is off by default.

Option Values Default Description
allowSigned true false false Merge a file that is signed. Its signature is lost, since a signature covers the bytes of its own file, and its visible appearance still prints. Without it, a signed file is an error
allowRestricted true false false Merge a file whose owner password restricts printing or copying. Without it, such a file is an error
doubleSided true false false Add a blank side after a document with an odd number of pages, so that each document starts on a front side when the result is printed on both sides of the sheet

A file is described by two fields: name, the file’s name as you want it in errors (contract-b.pdf), and pdf, its bytes.

Each page of each file is drawn on a page of the merged file, in the order of the files and of their pages. A page is drawn as a viewer shows it.

  • Size. The page has the size it shows at: its crop box, turned by the turn the file gives it. A file with pages of mixed sizes prints with mixed sizes, and the paper is left to whoever prints.
  • Content. The page looks as it did: text, images, vectors and transparency are drawn from the file’s own content, with its fonts. Nothing is converted or rendered to pixels.
  • Annotations. An annotation that prints is drawn from its stored appearance, over the page’s content. It prints when its Print flag is set and its Hidden flag is not. A check box or a radio button draws the state it is in. Links and pop-ups draw nothing. An annotation with no stored appearance is not drawn: the merge draws what the file stores and nothing of its own, so a highlight or a note that a viewer draws from its properties alone does not print. The merged file holds no annotation, so a link does not work in it.
  • Form fields. A field is drawn from the appearance the file stores for it, filled or empty, and the form itself is gone: the merged file has no fields to fill. A field that has a value but no stored appearance would print blank, so it is an error (below), and so is a field that has a value in a form that asks a viewer to redraw its fields: what the file stored may be out of date.
  • Layers. A file’s layers, its optional content groups, are carried over. Each is on or off in the merged file as it prints in its file, so every viewer shows and prints what the original printed. A layer that does not print in its file does not show in the merged file either.
  • Version. The merged file’s PDF version is the highest among the files’.

What is not on the printed page is left behind: bookmarks, links and named destinations, form fields and their scripts, the document’s title, author and other properties, embedded files, and the structure of a tagged PDF. The merged file claims no PDF/A, PDF/UA or PDF/X and is not tagged, encrypted or linearized.

Printed on both sides of the sheet, a document with an odd number of pages ends on a front side, and the next document would start on the back of it. With doubleSided, one blank page the size of that document’s last page follows each document with an odd number of pages, so the next starts on a front side. None follows the last document. The blank page is empty, without the line a merge without a license key draws.

A merge refuses a file it would print wrong, where it can tell. Each of these is an error, a message that names the file and says what to change, in the error each SDK throws for a render:

A file that Error To merge it
Needs a password to open contract-b.pdf: the PDF needs a password to open, and a merge can't open it: remove the password first Remove the open password first
Has an owner password that restricts printing or copying contract-b.pdf: the owner restricts printing or copying: set the allow-restricted option to merge it anyway Set allowRestricted
Is signed contract-b.pdf: the file is signed, and a merge can't keep a signature, … Set allowSigned, which drops the signature
Has a form field with a value and no stored appearance contract-b.pdf: page 2: the form field 'name' has a value but no stored appearance, so it would print blank: … Open the file in a PDF viewer and save it, which stores the appearance
Has a form field with a value, in a form that asks a viewer to redraw its fields contract-b.pdf: page 2: the form field 'name' has a value, and the form asks a viewer to redraw its fields (NeedAppearances), so the stored appearance may be out of date and would print wrong: … Open the file in a PDF viewer and print it to a new PDF, which draws each field as the viewer shows it
Can’t be read, or isn’t a PDF notes.txt: the file is not a PDF: it doesn't start with %PDF- Give the PDF
Has no pages contract-b.pdf: the PDF has no pages Give a file with pages

A file that opens without a password but has an owner password is read as any other: the owner password only restricts what the file allows. An empty signature field is not a signature, and does not need allowSigned.

A merge with no files, or with more than 1,000, is an error too, and so is a merge that runs past the engine’s timeout or needs more than its maxMemoryMb.

Like a render, a merge works without a license key. Each merged page gets the Lpdf attribution line, the mark and the name, once, in the page’s top-right corner where a render puts its line, drawn over the page’s content. The line has no link, since the merged file holds no annotation, and the blank sides doubleSided adds stay empty. A free Community key removes it, and License key shows how to set one.

merge reads PDFs that make a page the way a viewer does. It is checked on files from these tools, in these PDF versions: Microsoft Word 2013, Adobe Acrobat Distiller 23, Adobe LiveCycle Designer ES 9.0 and Designer 6.5, Antenna House PDF Output Library 6.6, iText 7, Skia/PDF (Chrome’s print to PDF), macOS Quartz and Lpdf, in PDF 1.3, 1.4, 1.6 and 1.7, with and without compressed object streams.

It is also checked on files built for the structures those lack: pages turned by /Rotate, cut by a crop box and of mixed sizes, resources a page inherits or shares, content in several streams, annotations of each flag combination, form fields filled and empty, layers, owner passwords and a damaged cross-reference table.

Each result passes qpdf --check, and each page of it renders like the page it comes from.

A file that Lpdf’s reader can’t read is an error that names the file.