All Elements
Complete attribute reference for every lpdf XML element. Use Ctrl+F to find the element you need.
Lengths, tokens and colors are described in XML Schema.
Document structure
Section titled “Document structure”Root element.
| Attribute | Type | Required | Description |
|---|---|---|---|
version |
integer | yes | Schema version — always 1 |
assets
Section titled “assets”Container for font, image and color profile declarations. Comes before tokens and document.
| Attribute | Type | Description |
|---|---|---|
name |
string | Required. Alias used in the document. Lowercase letters, digits and -, starting with a letter |
core |
string | Built-in PDF font: Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats |
src |
path | Path of a .ttf or .otf file, read by the SDK from the machine that renders |
ref |
string | The key the font’s bytes are registered under with loadFont. Defaults to name |
A built-in font can also be used by its name without declaring it: font="Courier".
| Attribute | Type | Description |
|---|---|---|
name |
string | Required. Alias used in img elements. Same characters as a font name |
src |
path | Path of the image file (JPEG, PNG, WebP, GIF, TIFF, BMP or SVG: see Formats), read by the SDK from the machine that renders. URLs and data URIs are not fetched |
ref |
string | The key the image’s bytes are registered under with loadImage. Defaults to name |
An image needs either a readable src or bytes loaded with loadImage.
profile
Section titled “profile”An ICC color profile: the profile of the printing press a PDF/X document is made for, which the printer gives out. profile on output names it.
| Attribute | Type | Description |
|---|---|---|
name |
string | Required. Alias the profile of output uses. Same characters as a font name |
src |
path | Path of the .icc file, read by the SDK from the machine that renders |
ref |
string | The key the profile’s bytes are registered under with loadProfile. Defaults to name |
It has to be a printer profile, in gray, RGB or CMYK. The engine bundles no press profile.
tokens
Section titled “tokens”Container for custom scales, colors and spot colors, placed before document. See Tokens.
| Child | Description |
|---|---|
space, text-size, border, radius, width, height, grid |
Replace one scale. Each takes all six of xs s m l xl xxl, as lengths in pt, mm or in. height is the row for the heights of boxes, tables, images, shapes and barcodes: xs 16pt, s 24pt, m 32pt, l 48pt, xl 64pt, xxl 96pt |
line-height |
Replaces the line-height scale. It takes all six too, but as factors of the font size, not lengths: xs 1.0, s 1.1, m 1.2, l 1.4, xl 1.6, xxl 2.0 |
aliases |
Holds alias elements |
colors |
Holds color elements |
spots |
Holds spot elements |
gradients |
Holds gradient elements |
rulings |
Holds ruling elements |
A name of your own for a slot of the scale. An attribute that takes a slot (xs to xxl) takes the name in its place, and reads the slot of its own row: with caption for xs, font-size="caption" is the text size xs and gap="caption" the space xs. See Aliases.
| Attribute | Type | Description |
|---|---|---|
name |
string | Required. Lowercase letters, digits and -, starting with a letter. Not xs s m l xl xxl fill or full, which mean something already |
value |
string | Required. The slot the name stands for: xs s m l xl or xxl. Not another alias |
| Attribute | Type | Description |
|---|---|---|
name |
string | Required. Name to use in any color attribute. A color named text becomes the default text color |
value |
color | Required. #rgb, #rrggbb, cmyk(), rgb() or hsl(). See Colors |
A spot color: an ink of its own, printed from a plate of its own, in spots inside tokens. A color attribute takes its name, solid, or a tint of it after a space: background="brand 30%". See Spot colors.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. The name a color attribute gives. Lowercase letters, digits and -, starting with a letter. Not a name of colors |
ink |
string | — | Required. The ink’s name as the printer knows it, which names its plate, such as PANTONE 1665 C. Not All, None, Cyan, Magenta, Yellow or Black |
value |
color | — | Required. The color that stands in for the ink on a screen or a proof: #rgb, #rrggbb, cmyk(), rgb() or hsl(), not a color name |
overprint |
boolean | false |
Whether the ink prints on top of the inks under it, as a varnish or a die line does |
gradient
Section titled “gradient”A named blend of colors, in gradients inside tokens. A background or a fill uses it as gradient:name, and the blend spans the box it fills. Give from and to for two colors, or stop children for more. See Gradients.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. The name that follows gradient:. Lowercase letters, digits and -, starting with a letter |
type |
string | — | Required. linear or radial |
from |
color | — | The first color: hex, cmyk(), rgb(), hsl(), a color name, or a spot color or a tint of it. Used with to, when there are no stop children. For a radial gradient it is the center |
to |
color | — | The last color. Used with from. For a radial gradient it is the edge |
angle |
number | 0 |
The direction of a linear gradient, in degrees: 0 runs from the top to the bottom, 90 from the left to the right, 180 from the bottom to the top. A radial gradient has no direction |
A color at a place along a gradient. A gradient takes two or more, in increasing order, in place of from and to.
| Attribute | Type | Description |
|---|---|---|
offset |
percent | Required. Where the color is reached, from 0% (the start) to 100% (the end). Offsets must increase |
color |
color | Required. Hex, cmyk(), rgb(), hsl(), a color name, or a spot color or a tint of it. A gradient’s colors are never another gradient, and are all CMYK, all RGB, or all tints of one spot color |
ruling
Section titled “ruling”Lines on every page of a section that names it with ruling, in rulings inside tokens: ruled paper, squared paper, or a page cut into equal parts. It holds one or more lines. See Rulings.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. The name a section gives in ruling. Lowercase letters, digits and -, starting with a letter |
origin |
string | page |
The space the lines fill and a count divides: page, up to the trim edge, or margin, inside the margin of the section’s layout or markdown |
edges |
boolean | true | Whether the lines on the edges of that space are drawn |
ocg |
string | — | print or screen: the lines are only printed, or only shown on screen |
One set of lines of a ruling, cut by a step or a count in each direction. A direction with neither has no lines, and a step and a count in the same direction is an error. A cell narrower than 2.5pt is an error.
| Attribute | Type | Default | Description |
|---|---|---|---|
step |
length | — | The distance between two lines in both directions |
step-x |
length | — | The distance between the lines that run down the page. Takes the place of step |
step-y |
length | — | The distance between the lines that run across the page. Takes the place of step |
count |
whole number | — | Equal parts in both directions, from 1 to 100 |
count-x |
whole number | — | Equal columns, from 1 to 100. Takes the place of count |
count-y |
whole number | — | Equal rows, from 1 to 100. Takes the place of count |
color |
color | line-muted |
The color of the lines |
thickness |
token/length | 0.4pt |
A length or a name of the border row |
Document properties written to the PDF. Child of document, before the sections.
| Attribute | Type | Description |
|---|---|---|
title |
string | Document title |
author |
string | Author |
subject |
string | Subject |
keywords |
string | Keywords |
creator |
string | Creating application |
lang |
string | The language of the text, as a language tag such as en-US, which a screen reader reads it in. A PDF/UA document needs it, and a PDF/A document of level a takes it only as a language tag |
output
Section titled “output”How the PDF file is written, apart from what its pages show: whether it is encrypted, and what a reader may do with it, whether it is PDF/A, PDF/UA or PDF/X, whether it is linearized, and how strictly a Factur-X invoice keeps to its spec. Child of document, after meta and before the sections. The passwords are not here: they come with the render call.
| Attribute | Type | Default | Description |
|---|---|---|---|
encrypt |
string | — | aes-256 rc4-128: encrypts the PDF with this cipher, with the passwords of the render call. Without it the PDF is not encrypted, and passwords given to the render are an error |
allow |
list | nothing | What a reader may do without the owner password, separated by spaces: all, or any of print modify copy annotate fill-forms accessibility assemble. Without it, or with allow="", nothing is allowed. It needs encrypt |
pdfa |
string | — | 2a 2b 2u 3a 3b 3u: writes the PDF as PDF/A-2a, PDF/A-2b, PDF/A-2u, PDF/A-3a, PDF/A-3b or PDF/A-3u. Level a tags the file as pdfua does, without PDF/UA’s checks. The render needs createdOn, every text a font of assets, and the document no CMYK color, form field, barcode digits, encrypt, or attachments in part 2, and at level a no lang that is not a language tag and no character of Unicode’s private use area, each an error that says what to change. With 3a, 3b or 3u, an attachment named factur-x.xml or xrechnung.xml makes the PDF a Factur-X e-invoice |
pdfua |
string | — | 1: writes the PDF as PDF/UA-1, a tagged PDF a screen reader can read. It combines with pdfa, and with 2a or 3a the file is PDF/A level a too. The render needs createdOn, meta a title and a lang, every img and barcode of the layout outside a header or a footer an alt, and every text a font of assets, each an error that says what to change |
pdfx |
string | — | 4: writes the PDF as PDF/X-4, for a commercial printer, made for the press profile profile names. It combines with pdfua. Every page gets a TrimBox and a BleedBox, RGB is tied to sRGB, and links print as text. The render needs createdOn, meta a title, and every text a font of assets, and the document no form field, barcode digits, encrypt, pdfa or attachments, each an error that says what to change |
profile |
string | — | The profile of assets a PDF/X file is made for: the ICC profile of the printing press. It needs pdfx, and pdfx needs it |
linearize |
boolean | false |
Writes the PDF linearized, for fast web view: page 1 and hints that say where every other page is come first, so a viewer that fetches the file by ranges shows page 1 while the rest downloads. Each page then names only the fonts and images it draws. With encrypt the file is encrypted first and linearized last. Any change to the file afterwards ends the linearization |
facturx-strict |
boolean | false |
Refuses, in a Factur-X invoice, an invoice file whose mime is not text/xml or whose relationship its profile doesn’t allow, and another file with no mime or of a format the Factur-X spec doesn’t list. It does nothing in a document without factur-x.xml or xrechnung.xml |
attachments
Section titled “attachments”The files the PDF carries inside it, which a reader lists in its attachments panel: see Attachments. Child of document, after meta and output and before the sections. It holds one file for each file.
A file the PDF carries. Child of attachments. The SDK reads it from src, or it was loaded on the engine under its ref or name.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | required | The name a reader shows the file under and saves it as. Each file of a document has a name of its own |
src |
path | — | Where the SDK reads the file from, when it was not loaded on the engine |
ref |
string | the name | The key the file was loaded on the engine under |
mime |
string | application/octet-stream |
The type of the file, such as text/xml or application/pdf. A Factur-X invoice file defaults to text/xml |
relationship |
string | unspecified |
source data alternative supplement unspecified: how the file relates to the document. A Factur-X invoice file defaults to the one its profile asks for |
description |
string | — | A line about the file, which a reader shows beside its name |
document
Section titled “document”| Attribute | Type | Default | Description |
|---|---|---|---|
size |
string | a4 |
letter legal a3 a4 a5, or a custom "200pt 300pt" or "210mm 297mm", each size 3pt at least |
orientation |
string | portrait |
portrait landscape |
bleed |
length | — | How far each page reaches past its trim edge, such as 3mm, for a background or an image that runs off the page when it is cut. The page grows by it, its background fills it, and the layout keeps to the trimmed page. See PDF/X |
font |
string | Helvetica |
Default font: a built-in name or an asset name |
background |
color or gradient:name |
— | Page background: a color, or a gradient that spans the page |
footnote-counter |
string | section |
Where the numbers of the footnotes start over: page, section or document. A section’s own value overrides it |
debug |
boolean | false | Render layout boxes |
A document holds an optional meta, an optional output, optional attachments and one or more section elements. Any other attribute is an error, width, height, color, title and font-size among them, and the one for margin says it is set on the layout. Set a page size with size="200pt 300pt", and the title on meta.
section
Section titled “section”| Attribute | Type | Default | Description |
|---|---|---|---|
size |
string | inherit | Override page size for this section, each size 3pt at least. With grow, the starting size |
orientation |
string | inherit | Override orientation |
bleed |
length | inherit | Override the bleed for this section’s pages; 0mm takes it away |
background |
color or gradient:name |
inherit | Section background. A gradient spans the page |
ruling |
string | — | The name of a ruling of the tokens, whose lines are drawn on every page, under everything else and over the background |
footnote-counter |
string | inherit | Where the numbers of the footnotes in this section start over: page, section or document. Overrides the document’s |
title |
string | — | Section title. Accepted, but not used: the PDF’s outline takes its entries from bookmarks |
type |
string | — | toc: the section is the document’s table of contents, laid out last with the data $toc. One per document |
toc-indent-step |
token/length | 12pt |
In a table of contents, the left padding an entry gets for each level below the first |
page-start |
whole number | — | The number of the section’s first page, which starts a new run of pages: 1 restarts the count. 1 or more. Without it the pages count on from the section before. See Page numbers |
page-format |
string | the section before’s | How the page numbers are written: decimal, lower-alpha, upper-alpha, lower-roman or upper-roman. Past z, letters repeat: aa, bb, cc |
page-prefix |
string | the section before’s | Text before the page numbers, such as A-. "" takes it away |
columns |
whole number | 1 | Sets the section’s flow, a layout or a markdown, in this many columns, from 1 to 12: each fills like a small page, left to right, then the next page. See Columns |
column-gap |
token/length | l |
The space between two columns, as gap takes it. Ignored with one column |
column-rule |
border | — | A line in the middle of each gap between two columns that hold something, as border takes it: 0.5pt #cccccc. Ignored with one column |
column-fill |
string | auto |
How the columns of the last page fill: auto, in order like every other page, or balance, levelled. CSS’s default is balance. Ignored with one column |
grow |
string | — | Lets the page grow to fit the content, where it would start a new page or squeeze it: width, height or width height. size is then the starting size. Up to 14,400pt (200in) in each size; an error with columns or an inset. See A page that grows |
debug |
boolean | false | Render layout boxes |
A section can start with one bookmark, which marks its first page, followed by layers and at most one layout or one markdown, painted in the order they are written. A layer before the layout is painted under it, and a layer after it is painted over it. A section with neither is one page.
layout
Section titled “layout”The flowing content of a section. Its elements are layout elements.
| Attribute | Type | Default | Description |
|---|---|---|---|
margin |
spacing | 36pt |
The space between the page edges and the flowing content and its regions: 48pt, a token, or one to four values like "48pt 24pt". A layer ignores it |
markdown
Section titled “markdown”Markdown as the content of a section, in the place of a layout. It holds an optional markdown-styles and one markdown-content, and nothing else: the page, a header, a footer or a cover stay in the XML around it, and a layer draws a header or a footer in its margin. See Markdown.
| Attribute | Type | Default | Description |
|---|---|---|---|
margin |
spacing | 36pt |
The space between the page edges and the Markdown, as the margin of a layout |
font |
string | the document’s | The font of the Markdown, which a rule can change |
font-size |
token/length | m |
The size of its text, which a rule can change |
color |
color | the text token |
The color of its text, which a rule can change |
gap |
token/length | l |
The space between blocks |
bookmarks |
integer | 6 |
How many levels of headings are bookmarks, 0 to 6 |
debug |
boolean | false |
Draw the outline of each box |
markdown-styles
Section titled “markdown-styles”The rules that say how each part of a markdown looks, inside markdown. A rule is an element named after the Markdown it styles: h1 to h6, p, code, quote, li, a, strong, em, del, table, th and td. It takes the attributes of the Lpdf element it becomes, and an attribute it does not set stays as the file or the defaults have it. See Styling.
| Attribute | Type | Default | Description |
|---|---|---|---|
src |
string | — | A file of rules, whose root is a markdown-styles. The rules written inside override it, and it overrides the defaults. The SDK, the command line or the extension reads it, as it reads the src of a font or an image |
markdown-content
Section titled “markdown-content”The Markdown, inside markdown: written inline, best in a CDATA section, with the indent its lines share removed first, or read from the data. See Where the Markdown comes from.
| Attribute | Type | Default | Description |
|---|---|---|---|
data-value |
string | — | The path in the data of a string that holds the Markdown. The text written inside is what a document with no data shows |
Layout elements
Section titled “Layout elements”Layout elements live inside layout. Every one except region, span and bookmark takes data-source, data-if and data-if-not, and text and barcode take data-value. See Data Binding.
Shared box attributes
Section titled “Shared box attributes”column, row, grid, frame and td take these, beside their own:
| Attribute | Type | Default | Description |
|---|---|---|---|
gap |
token/length | 0 |
Space between children. Not on frame, which has one child |
padding |
spacing | 0 |
Space inside the edge: 8pt, a token, or one to four values like "8pt 16pt" |
width |
token/length/fill |
— | Fixed width, or fill: the full width, and in a row the width the other children leave. Not on td: the table’s cols sets cell widths |
height |
token/length/fill/full |
— | A length fixes the height, as a length or a name from the height row of tokens; fill takes what is left after siblings; full takes all the height available. Any of them stops the box splitting across pages |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
background |
color or gradient:name |
— | Background fill: a color, or a gradient that spans the box |
border |
BorderValue | — | Border, written "thickness color" |
radius |
token/length | 0 |
Corner radius |
color |
color | inherit | Color of the text inside. A text that sets none takes the nearest box’s, else the text color. See Text color in a box |
opacity |
0–1 | 1 |
How opaque the box and everything in it is, as one. See Opacity |
shadow |
string | — | A hard-edged shadow under the box: "x y color", with an optional opacity after the color. See Shadow |
font |
string | inherit | Font for the text inside |
font-size |
token/length | inherit | Font size for the text inside |
debug |
boolean | false | Draw the box outlines |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
column
Section titled “column”Vertical column of children.
| Attribute | Type | Default | Description |
|---|---|---|---|
align |
string | stretch |
Horizontal alignment: start center end stretch |
justify |
string | start |
Vertical distribution: start center end between |
bulk |
boolean | false |
true lays out the texts of its text with data-source a page at a time, straight from the data. See Bulk Records |
Children side by side, continuing on the next line when they run out of width. A child with width="fill" takes the width its line leaves, shared equally when several on the line use it, and never moves to the next line.
| Attribute | Type | Default | Description |
|---|---|---|---|
align |
string | start |
Vertical alignment on each line: start center end. stretch acts as start |
justify |
string | start |
Distribution along each line: start center end between. between puts the first child at the left edge, the last at the right, and the others evenly between |
Equal columns, filled left to right.
| Attribute | Type | Default | Description |
|---|---|---|---|
cols |
integer | 1 |
Number of columns (1–12) |
col-width |
token/length | — | Minimum column width: fits as many columns as the width allows, at least one, stretched to fill the row (overrides cols). Tokens are grid sizes |
bulk |
boolean | false |
true lays out the cells of its child with data-source a page at a time, straight from the data. See Bulk Records |
A list of items, each marked with a bullet drawn as a shape or a number the engine writes. Its children are li items. The items go top to bottom with gap between them, and a list inside an item nests. It takes the attributes of a box, and width. See List.
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | bullet |
bullet marks each item with a shape, number with a number |
bullet |
string | by depth | The shape of a bullet list: disc circle square dash. Without it a list uses a disc, one inside a bullet list a circle, and one inside that a square |
format |
string | decimal |
How a number list writes its numbers: decimal lower-alpha upper-alpha lower-roman upper-roman |
start |
integer | 1 |
The number of a number list’s first item |
prefix |
string | — | Text before each number of a number list |
suffix |
string | . |
Text after each number of a number list |
indent |
token/length | 24pt |
The width of the marker’s column: the words of an item start this far from the list’s left edge, at every level |
bulk |
boolean | false |
true lays out the items of its li with data-source a page at a time, straight from the data. See Bulk Records |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
One item of a list: a box that holds what a layout holds, beside the item’s marker. Its words go in a text. It takes the attributes of a box, which go around the marker and the content together, and its gap goes between its children: the gap of the list unless the item sets one. data-source repeats the item once for each entry of the data, and the numbers follow what is made. See List.
Single-child container with padding, border, and background. Always centres its child, so it takes no gap, align or justify, and a second child is an error.
Code, or any text whose spaces and lines matter, in a box. The text is kept as it is written: every space, and a new line wherever one is written, except the line break after the start tag and the indent of the line the end tag stands on. A line longer than the box wraps at a space, and a word with none breaks at the last character that fits. The box fills the width, in Courier on a light tint with padding m, and splits across pages between lines. Children: span, which colors parts of the code. See Code.
| Attribute | Type | Default | Description |
|---|---|---|---|
font |
string | Courier |
Font for the code |
font-size |
token/length | inherit | Font size for the code |
color |
color | inherit | Color of the code |
padding |
spacing | m |
Space between the edge of the box and the code |
background |
color | #f3f4f6 |
The tint of the box |
border, radius, opacity, shadow, width, height |
As on a box | ||
tab-size |
integer | 4 |
How many columns a tab fills to, 1 to 16 |
line-height |
number or token | 1.2 |
The distance between lines, as a factor of the font size |
widows, orphans |
integer | 2 |
The fewest lines of the code that may stand alone at the top or the bottom of a page when it splits |
paginate, debug |
As on a box | ||
data-value |
string | — | Dot-path to a string that replaces the code, as it is |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
Paragraph or inline text.
| Attribute | Type | Default | Description |
|---|---|---|---|
font |
string | inherit, else the document’s font, or Helvetica |
Font name |
font-size |
token/length | inherit, else m (11pt) |
Font size |
color |
color | the nearest box’s, else #1a1a1a |
Text color. A text that sets none takes the color of the nearest box that sets one, else the text color: a color named text in tokens changes the default |
align |
string | left |
left center right justify. Not inherited: on a box, align places the children |
width |
token/length | — | Constrain text block width |
line-height |
number or token | 1.2 (m) |
The distance between lines, as a factor of the font size: a number above 0, or a name from the line-height row of tokens |
max-lines |
integer | — | The most lines drawn. Only whole lines are drawn, and the rest of the text is dropped. No cap by default: the text wraps whole. See Capping a text |
ellipsis |
boolean | false |
End the last line drawn in an ellipsis when max-lines drops text. With no max-lines it changes nothing |
role |
string | — | h1 … h6: makes the text a heading, which a tagged document, with pdfua or a pdfa of level a, tags as one. It changes nothing a page shows. A document that is not tagged ignores it |
widows |
integer | 2 |
The fewest lines, 1 to 10, that a split paragraph may carry to the top of the next page. 1 turns it off |
orphans |
integer | 2 |
The fewest lines, 1 to 10, that a split paragraph may leave at the bottom of a page. 1 turns it off |
capture |
string | — | Records the words of this text under a name, for a header or a footer to show. See Running headers |
capture-ref |
string | — | In a region: shows what was recorded under the name, as of the page the text is on, in place of words of its own |
capture-mode |
string | last |
With capture-ref: first or last, which of the texts captured on the page it shows |
capture-fallback |
string | — | With capture-ref: what it shows until something has been captured in the section |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
debug |
boolean | false | Draw the box outline |
data-value |
string | — | Dot-path to a scalar value that replaces the text |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
Children: span for inline style overrides, code-span for a run of code, and fn for a footnote.
Inline text with overridden style.
| Attribute | Type | Description |
|---|---|---|
font |
string | Font override |
color |
color | Color override |
href |
URL | Makes the span a link: a URL, or #id to jump to the bookmark with that id |
bookmark-ref |
string | Makes the span a cross-reference to the bookmark with that id: a link to it. In its words, {bookmark-page} prints the page the bookmark is on, as that page’s footer prints it, and {bookmark-label} its label. An id no bookmark has, another {…} in the words, and href beside it are errors. See Referring to a bookmark |
underline |
boolean | Underline text |
strike |
boolean | Strikethrough text |
A space falls between a span and the text around it only where the text has whitespace there. See Spaces around a span.
code-span
Section titled “code-span”A run of code inside a text: its words in Courier on a light tint, drawn behind them. White space in it collapses as in the text around it, and like a span it is not broken inside. See Code.
| Attribute | Type | Default | Description |
|---|---|---|---|
font |
string | Courier |
Font override |
color |
color | the text’s | Color override |
background |
color | #f3f4f6 |
The tint behind the words |
A footnote, inside a text of the layout. Its place in the text shows a small raised number, and the words it holds go at the bottom of the page where that number lands, under a short rule, in the order of the numbers. It takes no attributes, and holds words and span elements. A page with notes has less room for its text, so a line whose note would not fit moves to the next page with it. The numbers start over where footnote-counter on the document or a section says.
Only a text of the layout can hold one: an fn in a text-at, a table or a region is an error. See Footnote.
divider
Section titled “divider”Horizontal (or vertical) rule.
| Attribute | Type | Default | Description |
|---|---|---|---|
direction |
string | horizontal |
horizontal or vertical |
color |
color | #000000 |
Line color |
thickness |
token/length | 1pt |
Line thickness. Tokens are border sizes: xs 0.5pt up to xxl 4pt |
debug |
boolean | false | Draw the box outline |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
img (layout)
Section titled “img (layout)”Inline image.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. Asset name |
alt |
string | — | What the image shows, which a screen reader reads in a tagged document, with pdfua or a pdfa of level a; alt="" marks it as decoration. A PDF/UA document needs it on each image outside a header or a footer; at level a without pdfua, an image without it is decoration. A document that is not tagged ignores it |
width |
token/length/fill |
— | Width, or fill: as wide as the room the image has. Without height, the height follows the image’s proportions |
height |
token/length | — | Height: a length, or a name from the height row of tokens. With both, they are a maximum: the image is never stretched. With width="fill", a limit |
padding |
spacing | 0 |
Space around the picture, inside the box |
background |
color | — | Background of the box around the picture |
border |
BorderValue | — | Border, drawn on the edge of the box |
radius |
token/length | 0 |
Corner radius: rounds the box, and clips the picture to rounded corners |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
debug |
boolean | false | Draw the box outline |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
width="fill" makes the picture as wide as the room it has: the column it is in, what the line of a row leaves after the other children (shared with the other fill children), or a table cell. Its height follows its proportions, and a height limits it. See Image.
An image that sets padding, background or border is a box around its picture: width and height size the picture, and the box is larger by the padding. With width="fill" the box takes the room, and the picture fills what the padding leaves. A radius alone clips the picture to rounded corners. See Image.
A rectangle, a circle or an ellipse in the flow, for a status dot, a color swatch or a progress bar. It takes room as an image does, has no children, and is drawn centered in its box. For a shape at a place on the page, use a layer. See Shape.
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | — | Required. rect circle ellipse |
width |
token/length | — | Width of a rect or an ellipse, which need it |
height |
token/length | — | Height of a rect or an ellipse, which need it: a length, or a name from the height row of tokens |
r |
length | — | Radius of a circle, which needs it. Its box is the square of side 2r |
radius |
token/length | — | Corner radius of a rect |
fill |
color or gradient:name |
— | Fill: a color, or a gradient that spans the shape |
stroke |
color | — | Stroke color |
stroke-width |
length | — | Stroke width |
stroke-dash |
string | — | Dash pattern: "4 3" |
opacity |
0–1 | 1 |
How opaque the shape is |
debug |
boolean | false | Draw the box outline |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
| Attribute | Type | Default | Description |
|---|---|---|---|
cols |
string | — | Required. Column widths, separated by spaces, in fr, pt, mm, in or %, or auto: "1fr 2fr", "100pt 1fr", "40mm 1fr". An entry that is none of these is an error |
border |
BorderValue | — | Grid lines between and around the cells |
stripe |
color | — | Alternating row background |
gap |
token/length | 0 |
Space between columns and between rows |
padding |
spacing | 0 |
Space between the table’s edge and its content. Not cell padding: set it on each td |
background |
color or gradient:name |
— | Background behind the whole table. A gradient spans the table |
width |
token/length | — | Fixed width |
height |
token/length/fill/full |
— | A length fixes the height, as a length or a name from the height row of tokens |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
debug |
boolean | false | Draw the box outline |
bulk |
boolean | false |
true lays out the rows of its tr with data-source a page at a time, straight from the data. See Bulk Records |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
A table holds an optional thead and any number of tr.
thead / tr
Section titled “thead / tr”| Attribute | Type | Description |
|---|---|---|
background |
color or gradient:name |
Row background. A gradient spans the row |
keep |
string | tr only. with-next keeps the row on the same page as the row after it: a run of such rows and the row that ends it move to the next page together. See Table |
ocg |
string | print or screen: shown only in print, or only on screen. See Print and screen content |
thead repeats at the top of every page. Both hold td cells.
Takes the shared box attributes, except width, which includes color, opacity and shadow. It accepts paginate, which has no effect on a cell, since a row never splits. Its own attributes:
| Attribute | Type | Default | Description |
|---|---|---|---|
align |
string | fill | start center end. By default children fill the cell width |
valign |
string | top |
top middle bottom |
colspan |
integer | 1 |
How many of the table’s columns the cell spans: as wide as them and the gaps between them. A row that spans more columns than cols names is an error. See Table |
rowspan |
integer | 1 |
How many rows the cell spans: as tall as them and the gaps between them, with the rows under it leaving its columns out. The rows it spans stay on one page. A row with a cell too many for the free columns, and a span past the last row, are errors; a thead takes no rowspan. See Table |
barcode
Section titled “barcode”| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | — | Required. qr datamatrix pdf417 code128 code39 ean13 ean8 upca gs1-128 gs1-datamatrix. See Barcode |
data |
string | — | Required. Barcode data payload |
alt |
string | — | What the barcode is for, which a screen reader reads in a tagged document, with pdfua or a pdfa of level a, in place of its data: “QR code to pay this invoice”. alt="" marks it as decoration. A PDF/UA document needs it on each barcode outside a header or a footer; at level a without pdfua, a barcode without it is decoration. A document that is not tagged ignores it |
width |
token/length | — | Width. Without height, the height follows the barcode’s proportions |
height |
token/length | — | Height of the whole barcode, with the digits of hrt inside it: a length, or a name from the height row of tokens. With both, they are a maximum: the barcode is never stretched |
ec |
string | — | Error correction: L M Q H for a qr (M without it), 0 to 8 for a pdf417 |
hrt |
boolean | false | Human-readable text below a linear barcode: code128 code39 ean13 ean8 upca gs1-128 |
rows |
integer | — | Rows of a pdf417 (3 to 90) or a Data Matrix (a size of the standard’s) |
columns |
integer | — | Columns of a pdf417 (1 to 30 codewords) or a Data Matrix (a size of the standard’s) |
check |
boolean | false | The mod 43 check character of a code39 |
data-value |
string | — | Dot-path to a scalar value that replaces the data the barcode encodes |
color |
color | #000000 |
Bar color |
background |
color | — | Background color |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
debug |
boolean | false | Draw the box outline |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
Clickable hyperlink wrapper.
| Attribute | Type | Description |
|---|---|---|
href |
URL | Required. Link target: a URL, or #id to jump to the bookmark with that id. Fixed: data-value does not change it |
gap |
spacing | Gap between child elements |
debug |
boolean | Draw the box outline |
ocg |
string | print or screen: shown only in print, or only on screen. See Print and screen content |
In an entry of a table of contents, href="#" on a link or a span jumps to that entry’s bookmark.
bookmark
Section titled “bookmark”An entry of the PDF’s outline and a target for href="#id" links and bookmark-ref cross-references. It draws nothing, and marks the element that follows it, which must be in the same container. Directly inside a section, as its first child, it marks the section’s first page. Not allowed in a layer. See Bookmark.
| Attribute | Type | Default | Description |
|---|---|---|---|
label |
string | — | Required. The text of the entry, in the outline and in a table of contents |
level |
integer | 1 |
Depth in the outline, 1 to 6. An entry nests under the closest entry before it with a lower level |
id |
string | from label |
The name links jump to. Without it, the label lowercased with other characters than letters and digits turned into hyphens, and -2, -3 added when the id is taken. Two bookmarks may not have the same id |
ref-only |
boolean | false |
true leaves the bookmark out of the outline and the table of contents; links and cross-references still reach it |
PDF form field.
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | — | Required. text checkbox dropdown radio button |
name |
string | — | Required. Field name in the PDF form |
value |
string | — | Default value |
label |
string | — | Visible label (checkbox, radio, button) |
options |
string | — | Comma-separated options (dropdown) |
group |
string | — | Radio group name |
checked |
boolean | false | Initial checked state (checkbox/radio) |
required |
boolean | false | Mark field as required |
readonly |
boolean | false | Prevent editing |
max-len |
integer | — | Maximum text length |
action-url |
URL | — | Submit URL (button) |
width |
token/length | — | Field width |
height |
token/length | — | Field height: a length, or a name from the height row of tokens |
debug |
boolean | false | Draw the box outline |
ocg |
string | — | screen: shown only on screen. print is an error: a field in print content could be filled nowhere. See Print and screen content |
region
Section titled “region”Pinned header or footer that repeats across pages. Only allowed directly inside layout. pin chooses the edge wherever the region is written among the flow, and regions on one edge stack in the order written. In its text, {page} is the page’s number and {pages} how many pages its run has (see Page numbers), and a text with capture-ref shows what the flow captured on its page (see Running headers).
| Attribute | Type | Default | Description |
|---|---|---|---|
pin |
string | — | Required. top or bottom, or inset for a block inside the section’s columns. left and right pass validation but are not implemented yet |
page |
string | each |
each first last odd even, or numbers and ranges such as 2-last. odd and even follow the number printed on the page, and the rest count the section’s own pages: see Odd and even pages. An inset on last goes on the last page of the flow filled without it, and stays there if it pushes text on to a new page |
top |
length | — | An inset only, and required with it: how far below the top of the columns it starts |
height |
length | — | An inset only, and required with it: how tall it is. Content taller than it is clipped at its foot; an inset that reaches below the room the headers and footers leave is an error |
col |
whole number | 1 | An inset only: the column it starts in, from 1 |
colspan |
whole number | 1 | An inset only: how many columns it covers. Past the section’s columns is an error |
debug |
boolean | false | Draw the region’s outline |
With pin="inset" the region is an inset: a block at a spot in the section’s columns, which the columns it covers fill above and carry on below. See Insets.
Layer elements
Section titled “Layer elements”Layer elements live inside a layer, which is a child of section. Positions and sizes take pt, mm or in. A layer reads single values: text-at, img-at, barcode-at and the layer itself take data-if and data-if-not, and text-at and barcode-at take data-value. data-source is not allowed. See Layer.
Fixed content, in the order it is written among the section’s layers and layout.
| Attribute | Type | Default | Description |
|---|---|---|---|
page |
string | each |
each first last odd even, or numbers and ranges such as 2-last. odd and even follow the number printed on the page, and the rest count the section’s own pages: see Odd and even pages |
opacity |
0–1 | 1 | Opacity of everything in the layer as one. 0 draws nothing |
transform |
string | — | translate(x, y), scale(s), rotate(deg, cx, cy) or matrix(a, b, c, d, e, f), with plain numbers |
clip |
string | — | A rectangle, x y w h, in points from the top left corner of the page: what the layer draws outside it is cut off |
font |
string | the document’s font, or Helvetica |
The font of the text-at in the layer that sets none of its own |
font-size |
token/length | m (11pt) |
The size of the text-at in the layer that sets none of its own |
color |
color | #1a1a1a |
The color of the text-at in the layer that sets none of its own. Defaults to the text color |
alt |
string | — | In a tagged document, with pdfua or a pdfa of level a, what the layer shows: a screen reader reads it as one figure at the layer’s place. Without it a layer is decoration, which a reader skips with its text |
data-if |
string | — | Draw the layer only when the value at the path is truthy |
data-if-not |
string | — | Draw the layer only when the value at the path is falsy |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
A layer cannot contain another layer.
| Attribute | Type | Default | Description |
|---|---|---|---|
x |
signed length | — | X of the left edge (or offset from anchor) |
y |
signed length | — | Y of the top edge (or offset from anchor) |
width |
length | — | Required. Width |
height |
length | — | Required. Height |
anchor |
string | — | Reference point |
fill |
color or gradient:name |
— | Fill: a color, or a gradient that spans the rectangle |
stroke |
color | — | Border color |
stroke-width |
length | 1pt |
Border width |
stroke-dash |
string | — | Dash pattern: "4 2" |
radius |
length | — | Corner radius |
shadow |
string | — | A hard-edged shadow under the shape: "x y color", with an optional opacity after the color. See Shadow |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
circle
Section titled “circle”| Attribute | Type | Default | Description |
|---|---|---|---|
x |
signed length | — | X of the left edge of the circle’s box, the square of side 2r around it (or offset from anchor) |
y |
signed length | — | Y of the top edge of the circle’s box (or offset from anchor) |
r |
length | — | Required. Radius |
anchor |
string | — | Reference point |
fill |
color or gradient:name |
— | Fill: a color, or a gradient that spans the circle’s box |
stroke |
color | — | Border color |
stroke-width |
length | 1pt |
Border width |
stroke-dash |
string | — | Dash pattern |
shadow |
string | — | A hard-edged shadow under the shape: "x y color", with an optional opacity after the color |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
ellipse
Section titled “ellipse”Takes the same attributes as circle, with rx and ry in place of r. Its box is 2rx wide and 2ry high.
| Attribute | Type | Description |
|---|---|---|
rx |
length | Required. Horizontal radius |
ry |
length | Required. Vertical radius |
| Attribute | Type | Default | Description |
|---|---|---|---|
x1 |
signed length | — | Required. Start X |
y1 |
signed length | — | Required. Start Y |
x2 |
signed length | — | Required. End X |
y2 |
signed length | — | Required. End Y |
stroke |
color | #000000 |
Line color |
stroke-width |
length | 1pt |
Line thickness |
stroke-dash |
string | — | Dash pattern: "4 2" |
line-cap |
string | butt |
butt round square |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
| Attribute | Type | Default | Description |
|---|---|---|---|
d |
string | — | Required. SVG path data |
fill |
color or gradient:name |
— | Fill: a color, or a gradient that spans the path’s bounding box |
stroke |
color | — | Stroke color |
fill-rule |
string | nonzero |
nonzero evenodd |
stroke-width |
length | 1pt |
Stroke width |
stroke-dash |
string | — | Dash pattern |
line-cap |
string | butt |
butt round square |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
text-at
Section titled “text-at”Text at a fixed place. It is the layout’s text: max-lines, ellipsis and line-height are the layout text’s attributes, with text-at’s own defaults (one line, and a width above 1). Its font, size and color default to its layer’s. Children: span, as in text.
| Attribute | Type | Default | Description |
|---|---|---|---|
x |
signed length | — | X of the left edge of the box (or offset from anchor) |
y |
signed length | — | Y of the top edge of the box (or offset from anchor) |
anchor |
string | — | Reference point |
width |
length | — | Width of the box. Without it the text is one line at its natural width |
max-lines |
integer | 1 |
The most lines drawn. Above 1 it needs a width |
ellipsis |
boolean | false |
End the last line drawn in an ellipsis when the text does not fit |
line-height |
number or token | 1.2 (m) |
The distance between lines, as a factor of the font size: a number above 0, or a name from the line-height row of tokens |
font |
string | the layer’s font, else the document’s, or Helvetica |
Font name |
font-size |
token/length | the layer’s, else m (11pt) |
Font size |
bold |
boolean | false |
The bold face of a built-in font |
color |
color | the layer’s, else #1a1a1a |
Text color. A color named text in tokens changes the default |
align |
string | left |
left center right justify, within width |
data-value |
string | — | Dot-path to a value that replaces the text |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
img-at
Section titled “img-at”An image at a fixed place. It needs width or height.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | — | Required. Asset name |
x |
signed length | — | X of the left edge of the box (or offset from anchor) |
y |
signed length | — | Y of the top edge of the box (or offset from anchor) |
anchor |
string | — | Reference point |
width |
length | — | Width. Without height, the height follows the image’s proportions |
height |
length | — | Height. With both, they are a maximum: the image is never stretched |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
barcode-at
Section titled “barcode-at”A barcode at a fixed place. It needs width or height.
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | — | Required. qr datamatrix pdf417 code128 code39 ean13 ean8 upca gs1-128 gs1-datamatrix |
data |
string | — | Required. Barcode data payload |
x |
signed length | — | X of the left edge of the box (or offset from anchor) |
y |
signed length | — | Y of the top edge of the box (or offset from anchor) |
anchor |
string | — | Reference point |
width |
length | — | Width. Without height, the height follows the barcode’s proportions |
height |
length | — | Height of the whole barcode, with the digits of hrt inside it. With both, they are a maximum: the barcode is never stretched |
ec |
string | — | Error correction: L M Q H for a qr (M without it), 0 to 8 for a pdf417 |
hrt |
boolean | false |
Human-readable text below a linear barcode: code128 code39 ean13 ean8 upca gs1-128 |
rows |
integer | — | Rows of a pdf417 (3 to 90) or a Data Matrix (a size of the standard’s) |
columns |
integer | — | Columns of a pdf417 (1 to 30 codewords) or a Data Matrix (a size of the standard’s) |
check |
boolean | false |
The mod 43 check character of a code39 |
color |
color | #000000 |
Bar color |
background |
color | — | Background color |
data-value |
string | — | Dot-path to a value that replaces the data the barcode encodes |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
Anchor values
Section titled “Anchor values”Used by layer elements (x/y are offsets from the anchor point, and the element’s matching point is placed there). The points are on the whole page, not inside the margin:
| Value | Description |
|---|---|
top-left |
Top-left corner of the page |
top-center |
Top centre |
top-right |
Top-right corner |
center-left |
Middle of the left edge |
center |
Page centre |
center-right |
Middle of the right edge |
bottom-left |
Bottom-left corner |
bottom-center |
Bottom centre |
bottom-right |
Bottom-right corner |