XML Schema
lpdf documents are described in XML. Download the schema: lpdf.xsd (version="1", what this page documents).
Document structure
Section titled “Document structure”<lpdf version="1"> <assets> ← optional: fonts, images, color profiles <tokens> ← optional: custom scales, aliases, colors, spot colors, gradients and rulings <document> ← required <meta> ← optional: title, author, subject, keywords, creator, lang <output> ← optional: encryption, what a reader may do, PDF/A, PDF/UA, PDF/X <attachments> ← optional: the files the PDF carries <section>+ ← one or more, each with its own pages <bookmark> ← optional: marks the section's first page <layer>* ← fixed content, painted under the layout …shapes, text-at, img-at, barcode-at <layout> ← optional: flow content, at most one …elements <markdown> ← or Markdown in the place of the layout <layer>* ← fixed content, painted over the layoutA document nests 100 levels at most: the elements that enclose one another on one path from <lpdf>, <lpdf> included, so siblings don’t add up. A list inside a list nests two levels for each, its list and its li. A markdown is level 4, as a layout is, and its quotes and list items count too. A deeper document fails with an error that names the element: <text> at line 1, col 814 is nested 101 levels deep, past the limit of 100: a document nests 100 levels at most, <lpdf> included. A document built in code counts as its XML does, and its error names the type of the node: the node 'text' is nested 101 levels deep, ….
A container narrower than 2.5 mm (about 7.1pt), or with a height set lower, is too small to hold other containers. It draws its own box, with its background and border, its texts, images, shapes and other single elements, and its empty boxes, such as a swatch or a rule, but no column, row, grid, frame, link or table part inside it that holds something. A line of 6pt text is taller than that. It also ends grids nested in the cells of grids, which halve in width at each level.
A document holds sections, and a section holds any number of layers and at most one layout or one markdown, painted in the order they are written. The schema also allows layout directly inside document for a single section, but the engine does not accept that form yet: it stops with “unexpected element in document”. Always put it in a section.
<document size="letter"> <section> <layout margin="48pt"> <text>Hello world</text> </layout> </section></document>L.document({ size: 'letter' }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.text(NoAttr, ['Hello world']), ]), ]),])L.document(DocumentAttr(size='letter'), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.text(NoAttr, ['Hello world']) ]) ])])L.document(new DocumentAttr().size("letter"), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.text(NoAttr, List.of("Hello world")) )) ))))L.Document(new() { Size = "letter" }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Text(NoAttr, ["Hello world"]), ]), ]),])L::document(new DocumentAttr(size: 'letter'), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::text(NoAttr, ['Hello world']), ]), ]),])Attribute types
Section titled “Attribute types”Each attribute has the type the schema gives it, and the engine checks every attribute against it before it lays anything out. The reference tables name the types.
- A boolean is
trueorfalse, nothing else:bold="yes"andbold="1"are errors. - A whole number, such as a grid’s
colsor a list’sstart, and a number, such asopacityor a gradient’sangle, are written in digits, with a minus sign where the range allows one and a point for a fraction:opacity="0.5",start="-3". Each has the range the schema gives it: a grid’scolsgoes from 1 to 12,opacityfrom 0 to 1. line-heightis a name from the line-height row of the tokens, such asm, or a factor above 0, such as1.5.- Everything else is text, lengths with their unit included:
font-size="12pt".
A value that is not of its type is an error that names the element, the attribute and the type, such as <grid> at line 12, col 9: cols must be a whole number from 1 to 12, not "x". So is an attribute the element doesn’t have, which lists the ones it has: <gradient> at line 4, col 7: unknown attribute 'agle' — expected name, type, from, to, angle. The data-* attributes of data binding and the namespaced ones that point an editor at the schema, such as xsi:noNamespaceSchemaLocation, are left out of the check.
In code, the attribute objects of each SDK take the same types: bold: true, a grid’s cols: 3, opacity: 0.5, and lineHeight: 1.5 or 'm'. TypeScript, C# and Java refuse a value of another type when they compile, and the engine refuses it when it renders for Python and plain JavaScript, with the same error as for the XML. PHP refuses it when the object is made, but in a file without declare(strict_types=1) it first converts what it can, so bold: 'false' becomes true.
Page sizes
Section titled “Page sizes”Set on document, and overridden per section, with size. Without one, a document is A4.
| Value | Dimensions |
|---|---|
letter |
8.5 × 11 in |
legal |
8.5 × 14 in |
a3 |
297 × 420 mm |
a4 |
210 × 297 mm |
a5 |
148 × 210 mm |
Custom: size="200pt 300pt" or size="210mm 297mm", the width then the height, each a length in pt, mm or in. orientation="landscape" swaps the two.
Each size is 3pt at least, the smallest page PDF 1.7 recommends. A smaller one is an error: page size '80mm 0' is under 3pt high, the smallest page PDF 1.7 recommends. A page as long as its content, such as a till receipt, is a section that grows, with size as its starting size.
A length is a number and a unit: pt (a point, 1/72 in), mm or in. Every attribute that takes a length takes all three, and no other unit: cm, px and em stop the engine with an error that names the units. (% is a unit of a table’s cols, not of a length.) Millimeters and inches are worked out to points, so 1in is 72pt. Write the unit on every length. The one exception is 0, which needs none: 0, 0pt, 0mm and 0in are the same length. A page size takes no 0: a page is 3pt at least.
| Where | Accepts |
|---|---|
Layout lengths: gap, padding, margin, width, height, font-size, radius, thickness, toc-indent-step, the thickness of a border, the col-width of a grid |
a length, or a token name |
| The six values of a token row | a length |
A custom page size, such as "210mm 297mm" |
two lengths |
Layer positions and sizes: x y width height r rx ry x1…y2, and a layer’s radius and stroke-width |
a length |
Table cols |
fr, a length, % or auto |
A length in another unit is an error that says what it expects: invalid space value: '2cm': expected a slot from xs to xxl or a length in pt, mm or in. A layer’s x, y and the line ends are signed, so they accept negative numbers: -18pt.
Tokens
Section titled “Tokens”A token is a name for a length. Each attribute reads its own scale, so m is 8pt as a gap and 11pt as a font-size. The exception is line-height, whose tokens are factors of the font size, not lengths.
| Token | space: gap padding margin toc-indent-step |
text size: font-size |
border: border thickness |
radius |
width |
height |
grid: col-width |
line height: line-height |
|---|---|---|---|---|---|---|---|---|
xs |
2pt | 7pt | 0.5pt | 2pt | 120pt | 16pt | 60pt | 1.0 |
s |
4pt | 9pt | 1pt | 4pt | 200pt | 24pt | 100pt | 1.1 |
m |
8pt | 11pt | 1.5pt | 6pt | 280pt | 32pt | 140pt | 1.2 |
l |
14pt | 14pt | 2pt | 10pt | 360pt | 48pt | 180pt | 1.4 |
xl |
20pt | 20pt | 3pt | 16pt | 440pt | 64pt | 220pt | 1.6 |
xxl |
32pt | 28pt | 4pt | 24pt | 515pt | 96pt | 280pt | 2.0 |
width is a scale of page-wide measures, with no use for the height of a card or a row, so height has a row of its own: height="m" works on a box, a table, an img, a shape and a barcode. Before v0.29.0 a barcode or a form field read a token height from the width row.
padding and margin take one to four values, written like CSS, and each can be a token: padding="m 24pt" is 8pt top and bottom and 24pt left and right.
To change a scale, or to name colors, spot colors, gradients or rulings, add tokens before document. A scale row needs all six values:
<lpdf version="1"> <tokens> <space xs="2pt" s="6pt" m="12pt" l="18pt" xl="24pt" xxl="36pt"/> <colors> <color name="brand" value="#d76f04"/> <color name="text" value="#222222"/> </colors> </tokens> <document size="letter"> <section> <layout margin="48pt"> <column gap="m" padding="l" background="brand"> <text>Uses the new scale and the named color</text> </column> </layout> </section> </document></lpdf>L.document({ size: 'letter', tokens: { space: { xs: '2pt', s: '6pt', m: '12pt', l: '18pt', xl: '24pt', xxl: '36pt' }, colors: { brand: '#d76f04', text: '#222222' } } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.column({ gap: 'm', padding: 'l', background: 'brand' }, [ L.text(NoAttr, ['Uses the new scale and the named color']), ]), ]), ]),])L.document(DocumentAttr(size='letter', tokens=DocumentTokens(space={'xs': '2pt', 's': '6pt', 'm': '12pt', 'l': '18pt', 'xl': '24pt', 'xxl': '36pt'}, colors={'brand': '#d76f04', 'text': '#222222'})), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.column(ColumnAttr(gap='m', padding='l', background='brand'), [ L.text(NoAttr, ['Uses the new scale and the named color']) ]) ]) ])])L.document(new DocumentAttr().size("letter").tokens(new DocumentTokens().space(Map.of("xs", "2pt", "s", "6pt", "m", "12pt", "l", "18pt", "xl", "24pt", "xxl", "36pt")).colors(Map.of("brand", "#d76f04", "text", "#222222"))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.column(new ColumnAttr().gap("m").padding("l").background("brand"), List.of( L.text(NoAttr, List.of("Uses the new scale and the named color")) )) )) ))))L.Document(new() { Size = "letter", Tokens = new DocumentTokens(Space: new() { ["xs"] = "2pt", ["s"] = "6pt", ["m"] = "12pt", ["l"] = "18pt", ["xl"] = "24pt", ["xxl"] = "36pt" }, Colors: new() { ["brand"] = "#d76f04", ["text"] = "#222222" }) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Column(new() { Gap = "m", Padding = "l", Background = "brand" }, [ L.Text(NoAttr, ["Uses the new scale and the named color"]), ]), ]), ]),])L::document(new DocumentAttr(size: 'letter', tokens: new DocumentTokens(space: ['xs' => '2pt', 's' => '6pt', 'm' => '12pt', 'l' => '18pt', 'xl' => '24pt', 'xxl' => '36pt'], colors: ['brand' => '#d76f04', 'text' => '#222222'])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::column(new ColumnAttr(gap: 'm', padding: 'l', background: 'brand'), [ L::text(NoAttr, ['Uses the new scale and the named color']), ]), ]), ]),])The scale elements are space, text-size, border, radius, width, height, grid and line-height. A line-height row takes factors, not lengths: <line-height xs="1.0" s="1.1" m="1.2" l="1.4" xl="1.6" xxl="2.0"/>, and in code the factors are numbers: lineHeight: { xs: 1, s: 1.1, m: 1.2, l: 1.4, xl: 1.6, xxl: 2 }. A color named text becomes the default text color.
Aliases
Section titled “Aliases”An alias is a name of your own for a slot of the scale. Define it in aliases inside tokens, and use it wherever an attribute takes a slot (xs to xxl):
<lpdf version="1"> <tokens> <aliases> <alias name="caption" value="xs"/> <alias name="body" value="m"/> </aliases> </tokens> <document size="letter"> <section> <layout margin="48pt"> <column gap="body"> <text font-size="caption">Set in the text size xs</text> <text font-size="body">Set in the text size m</text> </column> </layout> </section> </document></lpdf>L.document({ size: 'letter', tokens: { aliases: { caption: 'xs', body: 'm' } } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.column({ gap: 'body' }, [ L.text({ fontSize: 'caption' }, ['Set in the text size xs']), L.text({ fontSize: 'body' }, ['Set in the text size m']), ]), ]), ]),])L.document(DocumentAttr(size='letter', tokens=DocumentTokens(aliases={'caption': 'xs', 'body': 'm'})), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.column(ColumnAttr(gap='body'), [ L.text(TextAttr(font_size='caption'), ['Set in the text size xs']), L.text(TextAttr(font_size='body'), ['Set in the text size m']) ]) ]) ])])L.document(new DocumentAttr().size("letter").tokens(new DocumentTokens().aliases(Map.of("caption", "xs", "body", "m"))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.column(new ColumnAttr().gap("body"), List.of( L.text(new TextAttr().fontSize("caption"), List.of("Set in the text size xs")), L.text(new TextAttr().fontSize("body"), List.of("Set in the text size m")) )) )) ))))L.Document(new() { Size = "letter", Tokens = new DocumentTokens(Aliases: new() { ["caption"] = "xs", ["body"] = "m" }) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Column(new() { Gap = "body" }, [ L.Text(new() { FontSize = "caption" }, ["Set in the text size xs"]), L.Text(new() { FontSize = "body" }, ["Set in the text size m"]), ]), ]), ]),])L::document(new DocumentAttr(size: 'letter', tokens: new DocumentTokens(aliases: ['caption' => 'xs', 'body' => 'm'])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::column(new ColumnAttr(gap: 'body'), [ L::text(new TextAttr(fontSize: 'caption'), ['Set in the text size xs']), L::text(new TextAttr(fontSize: 'body'), ['Set in the text size m']), ]), ]), ]),])An alias names a slot, not a row, so every row shares it: caption is the text size xs as a font-size, the space xs as a gap and the height xs as a height. When a document changes a row, the alias follows it. The one-to-four values of padding and margin, and the thickness of a border, take aliases too: padding="tight roomy", border="hairline #cccccc".
A name is lowercase letters, digits and -, and starts with a letter. It cannot be xs, s, m, l, xl, xxl, fill or full, which mean something already. Its value is a slot, not another alias, and a name defined twice is an error.
The engine catches a mistyped name, not the schema. An attribute that takes a slot accepts any name, so checking a document against the schema no longer flags gap="medum". The engine stops on it and says what it expects: invalid space value: 'medum': expected a slot from xs to xxl, an alias (body, caption) or a length in pt, mm or in.
Colors
Section titled “Colors”A color is written in one of four forms, or as the name of a color in tokens:
"#1763cf" ← hex: #rrggbb or #rgb"cmyk(91, 61, 0, 19)" ← cyan, magenta, yellow and black, each from 0 to 100"rgb(23, 99, 207)" ← red, green and blue, each from 0 to 255"hsl(215, 80%, 45%)" ← hue from 0 to 360, saturation and lightness from 0% to 100%"brand" ← a color named in tokens"brand 30%" ← a tint of a spot color named in tokensEach form goes wherever a color does: color, background, fill and stroke, the color of a border or a shadow, the colors of a gradient, and a value that data-color finds. A name that is not defined is an error. The value of a color in tokens is one of the four written forms, not a name.
- Screen and print. Hex,
rgb()andhsl()are screen colors, in RGB, andrgb()andhsl()give the same PDF as their hex:rgb(23, 99, 207)andhsl(215, 80%, 45%)are both#1763cf.hsl()makes shades of one color easy: keep the hue and change the lightness.cmyk()is a print color: the PDF has it as the four inks, so a printer separates its plates without converting it from RGB, which shifts colors. Lpdf never converts between the two. - Both in one document. RGB and CMYK colors can sit side by side, on one page or in sections of their own:
color="#1763cf"in a section for the screen andcolor="cmyk(91, 61, 0, 19)"in one for print. A gradient is the exception: its colors are all CMYK, all RGB, or all tints of one spot color (see Gradients). - Inks of their own. A brand color, a varnish or a die line that a printer prints from a plate of its own is a spot color.
- Standards and print. Which colors PDF/A, PDF/UA and PDF/X take, and what the press profile and the bleed do, is on Color and print.
- Commas or spaces. The values are separated by commas or by spaces, as in CSS:
cmyk(0, 0, 0, 100)andcmyk(0 0 0 100)are the same black. One color uses one or the other, sorgb(23, 99 207)is an error. - No alpha. A color is always solid:
rgba(23, 99, 207, 0.5)andrgb(23 99 207 / 50%)are errors. Useopacityon a layer or on a box, or the opacity of ashadow. - Keep print colors opaque. Whatever is faded, a layer or a box with an
opacitybelow 1 or a shadow with an opacity, is blended in RGB: itscmyk()colors are still written as inks, but they are converted to RGB to blend them, and so at print too. Leave the colors meant for print at full opacity.
A color is read strictly, so that a typo stops the render instead of printing the wrong color. Each of these is an error that names the value:
- a malformed color, such as
cmyk(0, 0, 100)with three values, or a part that is not a number - a value out of its range:
cmyk(0, 0, 0, 120),rgb(256, 0, 0), or a hue past 360, which does not wrap as in CSS, sohsl(2150, 80%, 45%)with a digit too many is not the red that 350 would be - a percentage in
rgb():rgb(9%, 39%, 81%). Write 0 to 255 hsl()without its%:hsl(215, 0.8, 0.45)would be a near-black gray, so the%is required
Spot colors
Section titled “Spot colors”A spot color is an ink of its own, printed from a plate of its own: a brand color such as a Pantone, a varnish, or a die line that marks where the sheet is cut. Declare each in spots inside tokens, with the ink’s name as the printer knows it and a color that stands in for it on a screen or a proof, and use its name wherever a color goes, solid or as a tint:
<lpdf version="1"> <tokens> <spots> <spot name="brand" ink="PANTONE 1665 C" value="cmyk(0, 85, 100, 0)"/> <spot name="varnish" ink="Varnish" value="cmyk(0, 0, 0, 10)" overprint="true"/> <spot name="die" ink="Dieline" value="#ff00ff" overprint="true"/> </spots> </tokens> <document size="a4"> <section> <layout margin="48pt"> <column gap="m"> <text font-size="xl" color="brand">Printed in PANTONE 1665 C</text> <row gap="s"> <column width="80pt" height="40pt" background="brand"/> <column width="80pt" height="40pt" background="brand 50%"/> <column width="80pt" height="40pt" background="brand 20%"/> </row> <column padding="l" background="cmyk(20, 0, 0, 0)" border="s die" radius="m"> <column height="40pt" background="varnish"/> </column> </column> </layout> </section> </document></lpdf>L.document({ size: 'a4', tokens: { spots: { brand: { ink: 'PANTONE 1665 C', value: 'cmyk(0, 85, 100, 0)' }, varnish: { ink: 'Varnish', value: 'cmyk(0, 0, 0, 10)', overprint: true }, die: { ink: 'Dieline', value: '#ff00ff', overprint: true } } } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.column({ gap: 'm' }, [ L.text({ fontSize: 'xl', color: 'brand' }, ['Printed in PANTONE 1665 C']), L.row({ gap: 's' }, [ L.column({ width: '80pt', height: '40pt', background: 'brand' }), L.column({ width: '80pt', height: '40pt', background: 'brand 50%' }), L.column({ width: '80pt', height: '40pt', background: 'brand 20%' }), ]), L.column({ padding: 'l', background: 'cmyk(20, 0, 0, 0)', border: 's die', radius: 'm' }, [ L.column({ height: '40pt', background: 'varnish' }), ]), ]), ]), ]),])L.document(DocumentAttr(size='a4', tokens=DocumentTokens(spots={'brand': {'ink': 'PANTONE 1665 C', 'value': 'cmyk(0, 85, 100, 0)'}, 'varnish': {'ink': 'Varnish', 'value': 'cmyk(0, 0, 0, 10)', 'overprint': True}, 'die': {'ink': 'Dieline', 'value': '#ff00ff', 'overprint': True}})), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.column(ColumnAttr(gap='m'), [ L.text(TextAttr(font_size='xl', color='brand'), ['Printed in PANTONE 1665 C']), L.row(RowAttr(gap='s'), [ L.column(ColumnAttr(width='80pt', height='40pt', background='brand')), L.column(ColumnAttr(width='80pt', height='40pt', background='brand 50%')), L.column(ColumnAttr(width='80pt', height='40pt', background='brand 20%')) ]), L.column(ColumnAttr(padding='l', background='cmyk(20, 0, 0, 0)', border='s die', radius='m'), [ L.column(ColumnAttr(height='40pt', background='varnish')) ]) ]) ]) ])])L.document(new DocumentAttr().size("a4").tokens(new DocumentTokens().spots(Map.of("brand", new Spot().ink("PANTONE 1665 C").value("cmyk(0, 85, 100, 0)"), "varnish", new Spot().ink("Varnish").value("cmyk(0, 0, 0, 10)").overprint(true), "die", new Spot().ink("Dieline").value("#ff00ff").overprint(true)))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.column(new ColumnAttr().gap("m"), List.of( L.text(new TextAttr().fontSize("xl").color("brand"), List.of("Printed in PANTONE 1665 C")), L.row(new RowAttr().gap("s"), List.of( L.column(new ColumnAttr().width("80pt").height("40pt").background("brand"), List.of()), L.column(new ColumnAttr().width("80pt").height("40pt").background("brand 50%"), List.of()), L.column(new ColumnAttr().width("80pt").height("40pt").background("brand 20%"), List.of()) )), L.column(new ColumnAttr().padding("l").background("cmyk(20, 0, 0, 0)").border("s die").radius("m"), List.of( L.column(new ColumnAttr().height("40pt").background("varnish"), List.of()) )) )) )) ))))L.Document(new() { Size = "a4", Tokens = new DocumentTokens(Spots: new() { ["brand"] = new Spot { Ink = "PANTONE 1665 C", Value = "cmyk(0, 85, 100, 0)" }, ["varnish"] = new Spot { Ink = "Varnish", Value = "cmyk(0, 0, 0, 10)", Overprint = true }, ["die"] = new Spot { Ink = "Dieline", Value = "#ff00ff", Overprint = true } }) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Column(new() { Gap = "m" }, [ L.Text(new() { FontSize = "xl", Color = "brand" }, ["Printed in PANTONE 1665 C"]), L.Row(new() { Gap = "s" }, [ L.Column(new() { Width = "80pt", Height = "40pt", Background = "brand" }), L.Column(new() { Width = "80pt", Height = "40pt", Background = "brand 50%" }), L.Column(new() { Width = "80pt", Height = "40pt", Background = "brand 20%" }), ]), L.Column(new() { Padding = "l", Background = "cmyk(20, 0, 0, 0)", Border = "s die", Radius = "m" }, [ L.Column(new() { Height = "40pt", Background = "varnish" }), ]), ]), ]), ]),])L::document(new DocumentAttr(size: 'a4', tokens: new DocumentTokens(spots: ['brand' => new Spot(ink: 'PANTONE 1665 C', value: 'cmyk(0, 85, 100, 0)'), 'varnish' => new Spot(ink: 'Varnish', value: 'cmyk(0, 0, 0, 10)', overprint: true), 'die' => new Spot(ink: 'Dieline', value: '#ff00ff', overprint: true)])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::column(new ColumnAttr(gap: 'm'), [ L::text(new TextAttr(fontSize: 'xl', color: 'brand'), ['Printed in PANTONE 1665 C']), L::row(new RowAttr(gap: 's'), [ L::column(new ColumnAttr(width: '80pt', height: '40pt', background: 'brand')), L::column(new ColumnAttr(width: '80pt', height: '40pt', background: 'brand 50%')), L::column(new ColumnAttr(width: '80pt', height: '40pt', background: 'brand 20%')), ]), L::column(new ColumnAttr(padding: 'l', background: 'cmyk(20, 0, 0, 0)', border: 's die', radius: 'm'), [ L::column(new ColumnAttr(height: '40pt', background: 'varnish')), ]), ]), ]), ]),])spot attribute |
Description |
|---|---|
name |
Required. The name a color gives: lowercase letters, digits and -, starting with a letter |
ink |
Required. The ink’s name as the printer knows it, which names its plate, such as PANTONE 1665 C. Any text but All, None, Cyan, Magenta, Yellow and Black, which PDF keeps for every plate, no plate and the four process plates |
value |
Required. The color that stands in for the ink: hex, cmyk(), rgb() or hsl(), not a color name |
overprint |
true prints the ink on top of the inks under it. Default false |
- Where it goes. Wherever a color does:
color,background,fillandstroke, the color of aborderor ashadow, the lines of a ruling, the colors of a gradient, and a value thatdata-colorfinds. - Tints. A percentage of the ink, after the name and a space:
background="brand 30%", from0%to100%, decimals allowed.brand 100%isbrand. Only a spot color takes a tint: for a color ofcolors, write the lighter color itself. - The plate. The PDF draws a spot color in a Separation color space named after its ink, so the printer’s tools print it from a plate of its own, and Acrobat’s Output Preview lists it. The
valueis what a screen, a proof or a printer without the ink shows in its place: acmyk()value keeps the stand-in in CMYK, any other form in RGB. Lpdf ships no ink library: the name and the stand-in are yours. - Overprint. An ink that overprints prints on top of the inks under it, instead of leaving them out where it sits. A varnish needs it, or the picture under it is not printed, and so does a die line, or the artwork has a white gap where the cutter runs. A screen doesn’t show overprint: Acrobat’s Overprint Preview and a press do.
- Gradients. A gradient of a spot color runs between tints of that one ink:
from="brand" to="brand 10%". One that mixes a spot color with any other color, another spot color included, is an error that names both. - Names. A spot color can’t share its name with a color the document’s
colorswrites. It may take the name of a built-in color, such asprimary, and is then used in its place. - Standards. A PDF/X file keeps each ink as its plate, and a
cmyk()value needs a CMYK press profile there. A PDF/A file takes spot colors whosevalueis an RGB color, which its sRGB output intent covers.
Each of these is an error that says what to change:
- a tint of a color that is not a spot color, such as
primary 30% - a tint out of its range, such as
brand 130%, or without its%, such asbrand 30 - a spot color declared twice, two spot colors with one ink, or an ink named
All,None,Cyan,Magenta,YelloworBlack - a
valuethat is a color name, or a malformed color
Gradients
Section titled “Gradients”A gradient is a named blend of colors. Define it once in gradients inside tokens, and use it as gradient:name where a background or a fill goes. It spans the box it fills.
gradient attribute |
Description |
|---|---|
name |
Required. The name that follows gradient:: lowercase letters, digits and -, starting with a letter |
type |
Required. linear or radial |
from, to |
The first and the last color, for two colors: hex, cmyk(), rgb(), hsl(), a color name, or a spot color or a tint of it |
angle |
The direction of a linear gradient, in degrees. Default 0 |
For more than two colors, give stop children in place of from and to. Each has an offset, a percentage from 0% to 100%, and a color. The offsets must increase. The first color holds up to the first stop, and the last color after the last stop.
- Where it goes. The
backgroundofcolumn,row,grid,frame,td,table,thead,tr,sectionanddocument, and thefillofrect,circle,ellipseandpath. A stroke, a text’scolorand the backgrounds ofbarcode,imgandfieldtake colors only, andgradient:there is an error. - Angle.
0runs from the top to the bottom,90from the left to the right, and180from the bottom to the top.45runs from the top-left corner to the bottom-right. The line is as long as the box needs, so the first and last colors reach the corners. - Radial. A circle at the center of the box, out to its farthest corner:
fromis the center andtothe edge. - Colors. Any color or a color name, never another gradient. A color name in a gradient is looked up after the
colorsare read, so the order intokensdoes not matter. - One color space. A PDF shading has one color space, so a gradient’s colors are all
cmyk(), or all hex,rgb()andhsl(), or all tints of one spot color. A gradient that mixes them is an error that names it, since converting one kind to the other would change the colors. - Pages. A box that splits across pages gets its own gradient on each page. The
backgroundof a page or a section spans the page. - Border, shadow and opacity. A border is drawn flat over the gradient, and a shadow under it. A box’s
opacityfades the gradient with the rest.
One document with each kind: two colors, three stops, and a radial gradient on a layer shape.
<lpdf version="1"> <tokens> <gradients> <!-- two colors, from the left to the right --> <gradient name="sky" type="linear" from="#1763cf" to="#0f3e8a" angle="90"/> <!-- several colors: stops --> <gradient name="sunset" type="linear" angle="90"> <stop offset="0%" color="#f97316"/> <stop offset="55%" color="#ec4899"/> <stop offset="100%" color="#8b5cf6"/> </gradient> <!-- from the center out to the farthest corner --> <gradient name="spotlight" type="radial" from="#ffffff" to="#1763cf"/> </gradients> </tokens> <document size="letter"> <section> <layout margin="48pt"> <column gap="m"> <column padding="l" background="gradient:sky" color="#ffffff" radius="m"> <text font-size="l">Two colors</text> </column> <column padding="l" background="gradient:sunset" color="#ffffff" radius="m"> <text font-size="l">Three stops</text> </column> </column> </layout> <layer> <circle x="400pt" y="520pt" r="60pt" fill="gradient:spotlight"/> </layer> </section> </document></lpdf>L.document({ size: 'letter', tokens: { gradients: { sky: { type: 'linear', from: '#1763cf', to: '#0f3e8a', angle: 90 }, sunset: { type: 'linear', angle: 90, stops: [{ offset: '0%', color: '#f97316' }, { offset: '55%', color: '#ec4899' }, { offset: '100%', color: '#8b5cf6' }] }, spotlight: { type: 'radial', from: '#ffffff', to: '#1763cf' } } } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.column({ gap: 'm' }, [ L.column({ padding: 'l', background: 'gradient:sky', color: '#ffffff', radius: 'm' }, [ L.text({ fontSize: 'l' }, ['Two colors']), ]), L.column({ padding: 'l', background: 'gradient:sunset', color: '#ffffff', radius: 'm' }, [ L.text({ fontSize: 'l' }, ['Three stops']), ]), ]), ]), L.layer(NoAttr, [ L.circle({ x: '400pt', y: '520pt', r: '60pt', fill: 'gradient:spotlight' }), ]), ]),])L.document(DocumentAttr(size='letter', tokens=DocumentTokens(gradients={'sky': {'type': 'linear', 'from': '#1763cf', 'to': '#0f3e8a', 'angle': 90}, 'sunset': {'type': 'linear', 'angle': 90, 'stops': [{'offset': '0%', 'color': '#f97316'}, {'offset': '55%', 'color': '#ec4899'}, {'offset': '100%', 'color': '#8b5cf6'}]}, 'spotlight': {'type': 'radial', 'from': '#ffffff', 'to': '#1763cf'}})), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.column(ColumnAttr(gap='m'), [ L.column(ColumnAttr(padding='l', background='gradient:sky', color='#ffffff', radius='m'), [ L.text(TextAttr(font_size='l'), ['Two colors']) ]), L.column(ColumnAttr(padding='l', background='gradient:sunset', color='#ffffff', radius='m'), [ L.text(TextAttr(font_size='l'), ['Three stops']) ]) ]) ]), L.layer(NoAttr, [ L.circle(CircleAttr(x='400pt', y='520pt', r='60pt', fill='gradient:spotlight')) ]) ])])L.document(new DocumentAttr().size("letter").tokens(new DocumentTokens().gradients(Map.of("sky", new Gradient().type("linear").from("#1763cf").to("#0f3e8a").angle(90.0), "sunset", new Gradient().type("linear").angle(90.0).stops(List.of(new GradientStop().offset("0%").color("#f97316"), new GradientStop().offset("55%").color("#ec4899"), new GradientStop().offset("100%").color("#8b5cf6"))), "spotlight", new Gradient().type("radial").from("#ffffff").to("#1763cf")))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.column(new ColumnAttr().gap("m"), List.of( L.column(new ColumnAttr().padding("l").background("gradient:sky").color("#ffffff").radius("m"), List.of( L.text(new TextAttr().fontSize("l"), List.of("Two colors")) )), L.column(new ColumnAttr().padding("l").background("gradient:sunset").color("#ffffff").radius("m"), List.of( L.text(new TextAttr().fontSize("l"), List.of("Three stops")) )) )) )), L.layer(NoAttr, List.of( L.circle(new CircleAttr().x("400pt").y("520pt").r("60pt").fill("gradient:spotlight")) )) ))))L.Document(new() { Size = "letter", Tokens = new DocumentTokens(Gradients: new() { ["sky"] = new Gradient { Type = "linear", From = "#1763cf", To = "#0f3e8a", Angle = 90 }, ["sunset"] = new Gradient { Type = "linear", Angle = 90, Stops = [new GradientStop { Offset = "0%", Color = "#f97316" }, new GradientStop { Offset = "55%", Color = "#ec4899" }, new GradientStop { Offset = "100%", Color = "#8b5cf6" }] }, ["spotlight"] = new Gradient { Type = "radial", From = "#ffffff", To = "#1763cf" } }) }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Column(new() { Gap = "m" }, [ L.Column(new() { Padding = "l", Background = "gradient:sky", Color = "#ffffff", Radius = "m" }, [ L.Text(new() { FontSize = "l" }, ["Two colors"]), ]), L.Column(new() { Padding = "l", Background = "gradient:sunset", Color = "#ffffff", Radius = "m" }, [ L.Text(new() { FontSize = "l" }, ["Three stops"]), ]), ]), ]), L.Layer(NoAttr, [ L.Circle(new() { X = "400pt", Y = "520pt", R = "60pt", Fill = "gradient:spotlight" }), ]), ]),])L::document(new DocumentAttr(size: 'letter', tokens: new DocumentTokens(gradients: ['sky' => new Gradient(type: 'linear', from: '#1763cf', to: '#0f3e8a', angle: 90), 'sunset' => new Gradient(type: 'linear', angle: 90, stops: [new GradientStop(offset: '0%', color: '#f97316'), new GradientStop(offset: '55%', color: '#ec4899'), new GradientStop(offset: '100%', color: '#8b5cf6')]), 'spotlight' => new Gradient(type: 'radial', from: '#ffffff', to: '#1763cf')])), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::column(new ColumnAttr(gap: 'm'), [ L::column(new ColumnAttr(padding: 'l', background: 'gradient:sky', color: '#ffffff', radius: 'm'), [ L::text(new TextAttr(fontSize: 'l'), ['Two colors']), ]), L::column(new ColumnAttr(padding: 'l', background: 'gradient:sunset', color: '#ffffff', radius: 'm'), [ L::text(new TextAttr(fontSize: 'l'), ['Three stops']), ]), ]), ]), L::layer(NoAttr, [ L::circle(new CircleAttr(x: '400pt', y: '520pt', r: '60pt', fill: 'gradient:spotlight')), ]), ]),])Rulings
Section titled “Rulings”A ruling is lines on every page of a section: ruled paper to write on, squared paper to draw on, or a grid to place things by. Define it once in rulings inside tokens, and name it on a section with ruling. Its lines are drawn under everything else on each page of the section, over its background.
ruling attribute |
Description |
|---|---|
name |
Required. The name a section gives in ruling: lowercase letters, digits and -, starting with a letter |
origin |
The space the lines fill and a count divides: page, the default, the whole page up to its trim edge, or margin, the area inside the margin of the section’s layout or markdown |
edges |
false leaves out the lines on the edges of that space. Default true |
ocg |
screen shows the lines on screen and doesn’t print them, and print prints them and doesn’t show them. See Print and screen |
A ruling holds one or more lines, each a set of lines of one color and thickness. They are drawn in order, so a later set paints over an earlier one.
lines attribute |
Description |
|---|---|
step |
The distance between two lines in both directions, a length such as 5mm |
step-x, step-y |
The distance in one direction: step-x between the lines that run down the page, step-y between the lines that run across it. Each takes the place of step in its direction |
count |
Cuts the space into this many equal parts in both directions, from 1 to 100 |
count-x, count-y |
The parts in one direction: columns or rows. Each takes the place of count in its direction |
color |
The color of the lines: any color or a color name. Default line-muted (#d4d4d4) |
thickness |
A length or a name of the border row. Default 0.4pt |
- A step or a count. A step makes cells of one size from the top left corner of the space, and leaves what is over at the right and the bottom. A count makes cells that stretch to fit, so the lines land on both edges. A direction with neither has no lines, so
step-yalone is ruled paper. A step and a count in the same direction is an error that names both. - Edges. With them, a count of 12 draws 13 lines, and a step draws a line on the start edge, and on the far edge when it lands there. Without them, the lines on the edges are left out: a count of 12 draws 11.
- The smallest cell is 2.5pt, so 1mm graph paper (2.83pt) fits. A smaller step is an error, and so is a count that cuts a page finer, with the count that fits:
ruling 'grid': a count of 100 cuts the area inside the margin into columns 2.28pt wide, narrower than the 2.5pt a ruling allows: give a count of 91 or less in x. - Page sizes. A step keeps its size on every page, and a count its number of parts.
- On the page. The lines stop at the trim edge of a page with a
bleed, run across the columns of a section withcolumns, and are decoration, which a screen reader skips. A section that holds only a ruling is one page of paper. - Size. The lines are written into the PDF once, and every page of the section refers to them, so a dense ruling makes a file no larger than a coarse one.
- Names. A section that names a ruling the tokens don’t declare is an error that lists the ones they do.
Graph paper in two sets, and ruled paper:
<lpdf version="1"> <tokens> <rulings> <!-- a fine line every 5mm and a heavier one every 25mm, inside the margin --> <ruling name="graph" origin="margin"> <lines step="5mm" color="#dde6f0" thickness="0.3pt"/> <lines step="25mm" color="#b5c4d6" thickness="0.6pt"/> </ruling> <!-- lines across the page every 8mm, none on its edges --> <ruling name="notes" edges="false"> <lines step-y="8mm" color="#cccccc"/> </ruling> </rulings> </tokens> <document size="a4"> <section ruling="graph"> <layout margin="40pt"> <text font-size="l">Graph paper</text> </layout> </section> <section ruling="notes"> <layout margin="40pt"> <text font-size="l">Notes</text> </layout> </section> </document></lpdf>L.document({ size: 'a4', tokens: { rulings: { graph: { origin: 'margin', lines: [{ step: '5mm', color: '#dde6f0', thickness: '0.3pt' }, { step: '25mm', color: '#b5c4d6', thickness: '0.6pt' }] }, notes: { edges: false, lines: [{ stepY: '8mm', color: '#cccccc' }] } } } }, [ L.section({ ruling: 'graph' }, [ L.layout({ margin: '40pt' }, [ L.text({ fontSize: 'l' }, ['Graph paper']), ]), ]), L.section({ ruling: 'notes' }, [ L.layout({ margin: '40pt' }, [ L.text({ fontSize: 'l' }, ['Notes']), ]), ]),])L.document(DocumentAttr(size='a4', tokens=DocumentTokens(rulings={'graph': {'origin': 'margin', 'lines': [{'step': '5mm', 'color': '#dde6f0', 'thickness': '0.3pt'}, {'step': '25mm', 'color': '#b5c4d6', 'thickness': '0.6pt'}]}, 'notes': {'edges': False, 'lines': [{'step-y': '8mm', 'color': '#cccccc'}]}})), [ L.section(SectionAttr(ruling='graph'), [ L.layout(LayoutAttr(margin='40pt'), [ L.text(TextAttr(font_size='l'), ['Graph paper']) ]) ]), L.section(SectionAttr(ruling='notes'), [ L.layout(LayoutAttr(margin='40pt'), [ L.text(TextAttr(font_size='l'), ['Notes']) ]) ])])L.document(new DocumentAttr().size("a4").tokens(new DocumentTokens().rulings(Map.of("graph", new Ruling().origin("margin").lines(List.of(new RulingLines().step("5mm").color("#dde6f0").thickness("0.3pt"), new RulingLines().step("25mm").color("#b5c4d6").thickness("0.6pt"))), "notes", new Ruling().edges(false).lines(List.of(new RulingLines().stepY("8mm").color("#cccccc")))))), List.of( L.section(new SectionAttr().ruling("graph"), List.of( L.layout(new LayoutAttr().margin("40pt"), List.of( L.text(new TextAttr().fontSize("l"), List.of("Graph paper")) )) )), L.section(new SectionAttr().ruling("notes"), List.of( L.layout(new LayoutAttr().margin("40pt"), List.of( L.text(new TextAttr().fontSize("l"), List.of("Notes")) )) ))))L.Document(new() { Size = "a4", Tokens = new DocumentTokens(Rulings: new() { ["graph"] = new Ruling { Origin = "margin", Lines = [new RulingLines { Step = "5mm", Color = "#dde6f0", Thickness = "0.3pt" }, new RulingLines { Step = "25mm", Color = "#b5c4d6", Thickness = "0.6pt" }] }, ["notes"] = new Ruling { Edges = false, Lines = [new RulingLines { StepY = "8mm", Color = "#cccccc" }] } }) }, [ L.Section(new() { Ruling = "graph" }, [ L.Layout(new() { Margin = "40pt" }, [ L.Text(new() { FontSize = "l" }, ["Graph paper"]), ]), ]), L.Section(new() { Ruling = "notes" }, [ L.Layout(new() { Margin = "40pt" }, [ L.Text(new() { FontSize = "l" }, ["Notes"]), ]), ]),])L::document(new DocumentAttr(size: 'a4', tokens: new DocumentTokens(rulings: ['graph' => new Ruling(origin: 'margin', lines: [new RulingLines(step: '5mm', color: '#dde6f0', thickness: '0.3pt'), new RulingLines(step: '25mm', color: '#b5c4d6', thickness: '0.6pt')]), 'notes' => new Ruling(edges: false, lines: [new RulingLines(stepY: '8mm', color: '#cccccc')])])), [ L::section(new SectionAttr(ruling: 'graph'), [ L::layout(new LayoutAttr(margin: '40pt'), [ L::text(new TextAttr(fontSize: 'l'), ['Graph paper']), ]), ]), L::section(new SectionAttr(ruling: 'notes'), [ L::layout(new LayoutAttr(margin: '40pt'), [ L::text(new TextAttr(fontSize: 'l'), ['Notes']), ]), ]),])BorderValue format
Section titled “BorderValue format”A border is a thickness and a color, separated by a space. The thickness is a token or a length in pt, mm or in:
"s #cccccc" ← token thickness + hex color"1.5pt #333333" ← pt thickness + hex color"0.4mm #333333" ← mm thickness + hex color"m brand" ← token thickness + color token"s cmyk(0 0 0 40)" ← token thickness + any other form of a colorA border with only a color, such as "#e0e0e0", is an error.
Element reference
Section titled “Element reference”See All Elements for a full attribute reference for every element.