Skip to content

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-

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.