Links, bookmarks and the outline¶
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>User manual</title>
<style>
@page { size: A5; margin: 15mm }
body { font: 10pt/1.4 sans-serif }
h1, h2 { break-before: page }
h1:first-of-type { break-before: auto }
/* the cover title is not a bookmark */
.cover { bookmark-level: none }
/* a bookmark that is not a heading, collapsed in the outline */
.faq { bookmark-level: 2; bookmark-label: "Questions"; bookmark-state: closed }
.faq dt { bookmark-level: 3; bookmark-label: content(text) }
</style>
</head>
<body>
<h1 class="cover" id="top">User manual</h1>
<p>Start with <a href="#install">Installation</a>, or read the
<a href="https://example.com/news">release notes</a> online.</p>
<h1 id="install">Installation</h1>
<h2>On Linux</h2>
<p>Back to the <a href="#top">top</a>.</p>
<h2>On Windows</h2>
<dl class="faq">
<dt>Does it need a network?</dt><dd>No.</dd>
<dt>Which fonts are used?</dt><dd>The system fonts and your own.</dd>
</dl>
</body>
</html>
kolinsky render links_manual.html -o manual.pdf --outline
kolinsky render links_manual.html -o install-only.pdf --outline --pages 2-
Links¶
Every <a> with a non-empty href becomes a clickable area in the PDF:
href |
link |
|---|---|
#name |
internal: jumps to the element with id="name" (or <a name="name">) |
| a URL that resolves to the document itself plus a fragment | internal, like #name |
any other URL, mailto: included |
external: opens the URL, resolved against the document's base URL |
A link split over two lines or two pages is clickable on each part, and so is every box inside it
(an image in a link, the text of its ::before and ::after).
An internal link whose target does not exist gives the diagnostic link.missing-anchor and is not
clickable; the rest of the document is unaffected.
Every element with an id (and every <a name>) is written as a named destination of the PDF, so a viewer
or another document can open the PDF at it (manual.pdf#install). When several elements share an id, the
first one counts.
<link rel="attachment" href="../..."> and <a rel="attachment"> embed files in the PDF; see
PDF output.
Bookmarks¶
A bookmark is an entry of the PDF outline, the table of contents a PDF viewer shows next to the pages. An
element is a bookmark when its bookmark-level is a number from 1 and its bookmark-label is not empty.
The headings h1 to h6 are bookmarks by default, at levels 1 to 6, labelled with their text.
| property | values |
|---|---|
bookmark-level |
none (default for most elements) or an integer from 1 |
bookmark-label |
a content list: content(text) (the element's text, the default for headings), content(before), content(after), attr(), counter(), strings |
bookmark-state |
open (default) shows the entry's children, closed folds them |
.cover h1 { bookmark-level: none } /* no bookmark for the cover title */
figure { bookmark-level: 3; bookmark-label: "Figure: " content(text) }
h1::before { content: counter(chapter) ". " }
h1 { bookmark-label: content(before) content(text) } /* "1. Introduction" */
Bookmarks nest by level: each entry becomes a child of the closest earlier entry with a smaller level, so a
skipped level (h1 then h3) leaves no gap. An element split over several pages gives one bookmark, at its
first part.
The outline¶
The outline is written when you ask for it: --outline on the command line, outline in the PDF options of
Rust (PdfOptions::outline) and Python (pdf={"outline": True}). Links and named destinations are written
in every case.
Writing part of the document¶
--pages (pages in Rust and Python) writes only some pages, for example 2- or 1-3,5. Links to a page
that is not written are dropped, and so are outline entries of such pages; their children move up to the
entry's parent. In the example above install-only.pdf starts at the installation chapter, and its link
back to the cover is gone.