PDF Output Options

A publisher job's look on paper is set in output.config. This page lists every option, what it accepts and what it does. Everything is optional: leave an option out and you get the default.

{
  "output": {
    "upload": { "url": "https://example.com/upload" },
    "config": {
      "type": "pdf",
      "color_mode": "cmyk",
      "dpi": 300,
      "bleed": 3,
      "pages": "1-2, 5",
      "crop_marks": true,
      "spreads_as_single_pages": true,
      "rotate_pages": [{ "page": 2, "degrees": 90 }],
      "add_blank_last_page": true
    }
  }
}

An invalid value is refused when the job is created, with a message naming the option — the job is not started.

Overview

Option	Type	Default	Accepts
type	string	pdf	pdf, png, jpg, jpeg, webp
color_mode	string	rgb	rgb, or cmyk for pdf, jpg and jpeg
dpi	integer	300	36 to 600
quality	integer	90	0 to 100 — JPEG only
bleed	number	the document's own	millimetres, 0 or more
pages	string	every page	page numbers and ranges — syntax below
crop_marks	boolean	false
spreads_as_single_pages	boolean	false
rotate_pages	list	none	{page, degrees} pairs — syntax below
add_blank_last_page	boolean	false
watermark	object	none	see below

How pages are numbered

pages and rotate_pages use the same numbering: the order in which the PDF puts out its pages, starting at 1.

• Without spreads_as_single_pages, every spread is one page of the PDF — a two-page spread counts as one.
• With spreads_as_single_pages, every page is a page of the PDF — a two-page spread counts as two.
• A cover wrap counts too. The editor's page bar leaves a cover wrap out of its page numbers; the PDF does not. In a document of four pages followed by a cover, the cover is page 5 here.

Numbers refer to the whole document, before any selection: with "pages": "8-11", page 9 in rotate_pages is still that page 9.

pages

Which pages to put out. Leave it out, or empty, for every page.

Write	Means
"3"	page 3
"2-5"	pages 2, 3, 4 and 5
"1-2, 8-11, 40"	pages 1, 2, 8, 9, 10, 11 and 40

The rules — the service checks them exactly:

• Parts are separated by a comma followed by one space: "1, 3". Without the space ("1,3"), with only spaces ("1 3"), or with a space before the comma, the job is refused.
• A range is two numbers joined by a hyphen, without spaces: "2-5", not "2 - 5".
• Numbers start at 1, without leading zeros: "0" and "07" are refused.
• The PDF keeps the document's order whatever order you write: "5, 2" puts out page 2, then 5.
• A number past the last page selects nothing; it is not an error.

crop_marks

Adds crop marks outside the page, for cutting it to its final size, and fold marks where two pages of a spread meet. Use it with a bleed, so the marks sit in the bleed area.

spreads_as_single_pages

Puts out each page of a spread as a page of its own. A two-page spread becomes two PDF pages, each with bleed on its three outer edges only — never on the fold.

rotate_pages

Turns chosen pages of the PDF. The page is turned whole — its content, bleed and crop marks together — and the document itself is not changed.

"rotate_pages": [
  { "page": 3, "degrees": 90 },
  { "page": 5, "degrees": 180 }
]

• page: a page number from 1, numbered as described above.
• degrees: 90, 180 or 270, clockwise.
• Each page may appear once.
• A page that is not put out (because of pages) is simply not there to turn.

The job is refused for a page below 1, any other number of degrees, or a page given twice.

add_blank_last_page

true adds one empty page after the last page — for a printer that needs an even page count, or a blank back.

• It has the size of the last page; when the last page is a spread, the size of one page of it.
• It gets the same bleed and crop marks as the page before it.
• Nothing is printed on it: no content, no page colour, no watermark. It is never rotated.

bleed

The bleed in millimetres, on every edge of every page, overriding what the document says. Leave it out to use each page's own bleed from the document.

dpi and quality

dpi is the resolution images are rendered at (36 to 600). quality is JPEG compression, 0 to 100, and only applies to jpg and jpeg output.

watermark

An image laid over every page.

"watermark": {
  "type": "center",
  "image": { "url": "https://example.com/watermark.png" },
  "width": 50,
  "height": 20,
  "opacity": 0.3
}

Property	Accepts
type	center (once, in the middle) or repeat_horizontal (repeated across the page)
image.url	the image; image.headers may carry up to 5 headers for fetching it
width, height	whole millimetres, 1 or more; optional
opacity	0 to 1; default 0.5

Availability

rotate_pages and add_blank_last_page are new in release 20261007 and work once the publisher service of that release is deployed. A service that predates them refuses a job that uses them; leave them out and the job runs as before.

See also: Publisher Service for creating jobs, CSV batches and downloads.