Bookmark

A bookmark adds an entry to the PDF’s outline, the bookmarks panel of a PDF viewer, and gives links a place to jump to. It draws nothing.

Attributes

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
id	string	from label	The name a link jumps to with href="#id". See Ids

Marking a heading

A bookmark marks the element that follows it. Put it just before a heading: when the heading moves to the next page, the bookmark moves with it, so the entry never points at the bottom of the page before.

XML

<column gap="m">
  <bookmark label="Introduction"/>
  <text font-size="xl">Introduction</text>
  <text>The text of the introduction.</text>
</column>

Node.js

L.column({ gap: 'm' }, [
    L.bookmark({ label: 'Introduction' }),
    L.text({ fontSize: 'xl' }, ['Introduction']),
    L.text(NoAttr, ['The text of the introduction.']),
])

Python

L.column(ColumnAttr(gap='m'), [
    L.bookmark(BookmarkAttr(label='Introduction')),
    L.text(TextAttr(font_size='xl'), ['Introduction']),
    L.text(NoAttr, ['The text of the introduction.'])
])

PHP

L::column(new ColumnAttr(gap: 'm'), [
    L::bookmark(new BookmarkAttr(label: 'Introduction')),
    L::text(new TextAttr(fontSize: 'xl'), ['Introduction']),
    L::text(NoAttr, ['The text of the introduction.']),
])

.NET

L.Column(new() { Gap = "m" }, [
    L.Bookmark(new() { Label = "Introduction" }),
    L.Text(new() { FontSize = "xl" }, ["Introduction"]),
    L.Text(NoAttr, ["The text of the introduction."]),
])

A bookmark needs an element after it in the same container. One that comes last, with nothing to mark, is an error.

Nesting

level nests the entries in the outline. An entry goes under the closest entry before it with a lower level, so a level 2 bookmark sits under the level 1 bookmark before it.

XML

<column gap="m">
  <bookmark label="Methods"/>
  <text font-size="xl">Methods</text>
  <bookmark label="Data collection" level="2"/>
  <text font-size="l">Data collection</text>
  <bookmark label="Sampling" level="3"/>
  <text font-size="m">Sampling</text>
</column>

Node.js

L.column({ gap: 'm' }, [
    L.bookmark({ label: 'Methods' }),
    L.text({ fontSize: 'xl' }, ['Methods']),
    L.bookmark({ label: 'Data collection', level: '2' }),
    L.text({ fontSize: 'l' }, ['Data collection']),
    L.bookmark({ label: 'Sampling', level: '3' }),
    L.text({ fontSize: 'm' }, ['Sampling']),
])

Python

L.column(ColumnAttr(gap='m'), [
    L.bookmark(BookmarkAttr(label='Methods')),
    L.text(TextAttr(font_size='xl'), ['Methods']),
    L.bookmark(BookmarkAttr(label='Data collection', level='2')),
    L.text(TextAttr(font_size='l'), ['Data collection']),
    L.bookmark(BookmarkAttr(label='Sampling', level='3')),
    L.text(TextAttr(font_size='m'), ['Sampling'])
])

PHP

L::column(new ColumnAttr(gap: 'm'), [
    L::bookmark(new BookmarkAttr(label: 'Methods')),
    L::text(new TextAttr(fontSize: 'xl'), ['Methods']),
    L::bookmark(new BookmarkAttr(label: 'Data collection', level: '2')),
    L::text(new TextAttr(fontSize: 'l'), ['Data collection']),
    L::bookmark(new BookmarkAttr(label: 'Sampling', level: '3')),
    L::text(new TextAttr(fontSize: 'm'), ['Sampling']),
])

.NET

L.Column(new() { Gap = "m" }, [
    L.Bookmark(new() { Label = "Methods" }),
    L.Text(new() { FontSize = "xl" }, ["Methods"]),
    L.Bookmark(new() { Label = "Data collection", Level = "2" }),
    L.Text(new() { FontSize = "l" }, ["Data collection"]),
    L.Bookmark(new() { Label = "Sampling", Level = "3" }),
    L.Text(new() { FontSize = "m" }, ["Sampling"]),
])

Bookmarking a section

A bookmark placed directly in a section, before its layers and its layout, marks the section’s first page. Use it for a page that has no layout to put a bookmark in, such as a cover drawn in a layer.

XML

<document size="a4">
  <section>
    <bookmark label="Cover"/>
    <layer>
      <text-at x="56pt" y="380pt" font-size="32pt">Annual Report</text-at>
    </layer>
  </section>
</document>

Node.js

L.document({ size: 'a4' }, [
    L.section(NoAttr, [
        L.bookmark({ label: 'Cover' }),
        L.layer(NoAttr, [
            L.textAt({ x: '56pt', y: '380pt', fontSize: '32pt' }, ['Annual Report']),
        ]),
    ]),
])

Python

L.document(DocumentAttr(size='a4'), [
    L.section(NoAttr, [
        L.bookmark(BookmarkAttr(label='Cover')),
        L.layer(NoAttr, [
            L.text_at(TextAtAttr(x='56pt', y='380pt', font_size='32pt'), ['Annual Report'])
        ])
    ])
])

PHP

L::document(new DocumentAttr(size: 'a4'), [
    L::section(NoAttr, [
        L::bookmark(new BookmarkAttr(label: 'Cover')),
        L::layer(NoAttr, [
            L::textAt(new TextAtAttr(x: '56pt', y: '380pt', fontSize: '32pt'), ['Annual Report']),
        ]),
    ]),
])

.NET

L.Document(new() { Size = "a4" }, [
    L.Section(NoAttr, [
        L.Bookmark(new() { Label = "Cover" }),
        L.Layer(NoAttr, [
            L.TextAt(new() { X = "56pt", Y = "380pt", FontSize = "32pt" }, ["Annual Report"]),
        ]),
    ]),
])

A section takes one bookmark there, as its first child. Elsewhere, bookmarks go in a layout. A layer cannot hold one.

Linking to a bookmark

href="#id" on a link or a span jumps to the bookmark with that id.

XML

<column gap="m">
  <text>See <span href="#results" color="#1a73e8" underline="true">Results</span> for the numbers.</text>
  <bookmark label="Results"/>
  <text font-size="xl">Results</text>
</column>

Node.js

L.column({ gap: 'm' }, [
    L.text(NoAttr, [
        'See ',
        L.span({ href: '#results', color: '#1a73e8', underline: 'true' }, ['Results']),
        ' for the numbers.',
    ]),
    L.bookmark({ label: 'Results' }),
    L.text({ fontSize: 'xl' }, ['Results']),
])

Python

L.column(ColumnAttr(gap='m'), [
    L.text(NoAttr, [
        'See ',
        L.span(SpanAttr(href='#results', color='#1a73e8', underline='true'), ['Results']),
        ' for the numbers.'
    ]),
    L.bookmark(BookmarkAttr(label='Results')),
    L.text(TextAttr(font_size='xl'), ['Results'])
])

PHP

L::column(new ColumnAttr(gap: 'm'), [
    L::text(NoAttr, [
        'See ',
        L::span(new SpanAttr(href: '#results', color: '#1a73e8', underline: 'true'), ['Results']),
        ' for the numbers.',
    ]),
    L::bookmark(new BookmarkAttr(label: 'Results')),
    L::text(new TextAttr(fontSize: 'xl'), ['Results']),
])

.NET

L.Column(new() { Gap = "m" }, [
    L.Text(NoAttr, [
        "See ",
        L.Span(new() { Href = "#results", Color = "#1a73e8", Underline = "true" }, ["Results"]),
        " for the numbers.",
    ]),
    L.Bookmark(new() { Label = "Results" }),
    L.Text(new() { FontSize = "xl" }, ["Results"]),
])

A link to an id that no bookmark has is left out of the PDF: its text is drawn, but it is not clickable.

Ids

Without an id, a bookmark takes one made from its label: lowercase, with every run of characters other than letters and digits turned into one hyphen. “Data collection” becomes data-collection, and “§ 3.1 — Methods” becomes 3-1-methods. When that id is taken, by an id set anywhere in the document or by an earlier bookmark, -2, -3 and so on are added: two bookmarks labeled “Summary” get summary and summary-2.

Set id when a link points at the bookmark, so the link keeps working when the label changes. Two bookmarks with the same id are an error, and so is an empty id.