Hyperlinks (hyperref)

Die meisten LaTeX-Pakete kümmern sich um ihren eigenen Bereich. hyperref nicht: Um \ref, \cite, Überschriften und das Inhaltsverzeichnis in anklickbare Links im PDF zu verwandeln, definiert es von innen heraus eine ganze Reihe LaTeX-eigener Befehle neu. Diese eine Tatsache erklärt fast alles Weitere – warum das Handbuch darauf besteht, es zuletzt zu laden, warum allein cleveref danach kommen muss und warum der rote Kasten um jeden Link das Erste ist, was die meisten abschalten. Diese Seite behandelt das Erscheinungsbild der Links, \href und \url, PDF-Metadaten und Lesezeichen sowie jene Warnung, die beim ersten Mathematiksatz in einer Überschrift garantiert auftaucht.

Was eine Zeile \usepackage{hyperref} in Links verwandelt

Ein \usepackage{hyperref} in der Präambel genügt: Ohne jede Konfiguration wird jeder Verweis im Dokument zum Link. \ref und \pageref, Zitate mit \cite, jeder Eintrag im Inhalts-, Abbildungs- und Tabellenverzeichnis, Fußnotenzeichen, Indexeinträge – alles, dessen Ziel sich bestimmen lässt. Ein Klick im PDF-Betrachter führt zum Ziel, eine URL öffnet den Browser. Manchmal ist ein Link jedoch unerwünscht. Die Verweisbefehle gibt es deshalb in gesternter Form: \ref*{key}, \pageref*{key} und \autoref*{key} geben die Nummer aus, ohne sie anklickbar zu machen.

Warum hyperref zuletzt geladen wird – und die eine Ausnahme

hyperref gehört fast ans Ende der Präambel, aus dem eingangs genannten Grund: Die Aufgabe dieses Pakets besteht darin, sehr viele LaTeX-Befehle neu zu definieren. Wird danach ein anderes Paket geladen, das dieselben Befehle anfasst, überschreibt es diese Neudefinitionen – Links und Lesezeichen brechen stillschweigend. Das hyperref-Handbuch formuliert diesen Rat unmissverständlich und versieht ihn mit einer Fußnote: Es sei bereits begonnen worden, die Zahl der Neudefinitionen und damit die Abhängigkeit von der Ladereihenfolge zu verringern. Es handelt sich also um einen gegenwärtigen Behelf, nicht um ein dauerhaftes Naturgesetz – die Ladereihenfolge allgemein behandelt die Seite zu Dokumentklasse und Präambel.

Von „zuletzt“ gibt es faktisch eine Ausnahme: cleveref. Es baut seine Verweisbefehle auf dem auf, was hyperref definiert hat; die umgekehrte Reihenfolge kann nicht funktionieren. Das scheitert nicht stillschweigend – das mit TeX Live 2024 gelieferte cleveref.sty prüft die Reihenfolge bei \begin{document} und bricht mit ! Package cleveref Error: cleveref must be loaded after hyperref! ab. Kommt varioref hinzu, lautet die Reihenfolge varioref → hyperref → cleveref. Etwas Weiteres untersagt das Handbuch ausdrücklich: hyperref darf nicht innerhalb von \AtBeginDocument oder des begindocument-Hooks geladen werden, da hyperref und nameref diesen Hook selbst nutzen und die Ausführungsreihenfolge dadurch heikel wird. Muss das Laden verzögert werden, ist der Hook begindocument/before der richtige.

\usepackage{graphicx}
\usepackage{amsmath}
% ... every other package ...
\usepackage{hyperref}   % almost last
\usepackage{cleveref}   % the exception: after hyperref

% With varioref in play, the prescribed order is:
%   varioref -> hyperref -> cleveref

colorlinks und hidelinks: den roten Kasten loswerden

Von Haus aus kennzeichnet hyperref einen Link mit einem farbigen Kasten darum herum (colorlinks ist standardmäßig false). Am Bildschirm fällt das zugegebenermaßen gut auf; auf Papier wird es zum Problem, denn der Kasten druckt mit, während der Link dort gar nicht existiert. Übrig bleiben rote Rechtecke im Text ohne erkennbaren Zweck – genau das meinen Leute, wenn sie sagen, hyperref habe ihr Layout „zerstört“. Konfiguriert wird das entweder über Optionen beim Laden oder nachträglich mit \hypersetup{...}, wobei key=value-Paare durch Kommas getrennt werden. \hypersetup darf an beliebiger Stelle der Präambel stehen.

Als Erstes wird meist colorlinks=true gesetzt. Damit entfällt der Kasten, stattdessen wird der Linktext selbst eingefärbt – das druckt sauber und liest sich am Bildschirm gut. Die Farben sind nach Art getrennt; voreingestellt sind Rot für linkcolor, Grün für citecolor, Magenta für urlcolor und Cyan für filecolor. Dieses Schema dient der Unterscheidbarkeit am Monitor und wirkt in einer eingereichten Arbeit recht laut. Zur schnellen Beruhigung setzt allcolors alle auf einen Wert; für druckorientierte Arbeiten lautet die Antwort hidelinks: weder Farbe noch Rahmen, die Links verschwinden optisch, bleiben aber anklickbar. Genau das passt zum Regelfall – ein Dokument, das als PDF verteilt und zugleich auf Papier gelesen wird.

\href und \url: Links nach draußen

Links auf externe URLs entstehen mit zwei Befehlen. \href{URL}{display text} hängt einen Link an beliebige Wörter; \url{URL} setzt die URL selbst in Festbreitenschrift und macht sie zugleich zum Link. \url also, wenn die Adresse im Text sichtbar sein soll, \href, wenn sie hinter anderen Wörtern verschwinden soll. Ihren Wert beziehen beide aus der Behandlung des Arguments: LaTeX-Sonderzeichen, von denen URLs voll sind – %, #, ~, _ –, lassen sich im URL-Teil wörtlich schreiben, ohne Escaping (im Argument von \url bleiben einige Einschränkungen). Wer nur die Festbreitenoptik ohne Link will, nimmt \nolinkurl{URL}.

See \href{https://www.ctan.org/pkg/hyperref}{the hyperref page on CTAN}.
% the words carry the link; the address is not shown

Download from \url{https://www.ctan.org/}.
% the address is typeset AND linked

\nolinkurl{https://example.com/a_b#c}
% monospaced, no link; underscore and hash need no escaping

Token not allowed in a PDF string und \texorpdfstring

Sobald in einer Überschrift Mathematik steht, gibt hyperref mit ziemlicher Sicherheit diese Warnung aus. Der Grund: Der Text einer Überschrift hat zwei Ziele – die gesetzte Überschrift im Text und eine reine Zeichenkette in den PDF-Lesezeichen. Ein Lesezeichen ist laut PDF-Spezifikation nichts als Text, ein $, ein ^ oder ein Befehl wie \emph kann darin also nicht vorkommen. hyperref verwirft jedes unbrauchbare Token und meldet einzeln, was es weggeworfen hat. Die Überschrift selbst wird weiterhin korrekt gesetzt; nur das Lesezeichen verliert seinen Inhalt – genau jene stille Verschlechterung, die entsteht, wenn man die Warnung übergeht.

Package hyperref Warning: Token not allowed in a PDF string (Unicode):
(hyperref)                removing `math shift' on input line 4.

Package hyperref Warning: Token not allowed in a PDF string (Unicode):
(hyperref)                removing `superscript' on input line 4.

Die Lösung heißt \texorpdfstring{für TeX}{für die PDF-Zeichenkette}. Das erste Argument dient dem Satz, das zweite dem Lesezeichen; so bekommt die Überschrift ihre Mathematik und das Lesezeichen eine ausgeschriebene Fassung: \section{The value of \texorpdfstring{$x^2$}{x squared}}. Ein Haken verdient Beachtung: Auch das zweite Argument wird zur PDF-Zeichenkette, ein dort geschriebenes x^2 verschiebt die Warnung also nur auf das ^. Darin darf keine Auszeichnung stehen – nur Zeichen, etwa x squared oder das Unicode-x².

PDF-Metadaten: pdftitle, pdfauthor und pdfusetitle

hyperref schreibt auch die Dokumentinformationen des PDF – jene Felder, die im Betrachter unter „Dokumenteigenschaften“ erscheinen, die ein Literaturverwaltungsprogramm importiert und viele Suchindizes auslesen. Gesetzt werden sie über \hypersetup mit pdftitle (Titel), pdfauthor (Autor), pdfsubject (Thema) und pdfkeywords (Schlagwörter). Ein Wert mit Komma oder Gleichheitszeichen kollidiert mit den Trennzeichen der Schlüssel; am sichersten ist es daher, Werte in geschweifte Klammern zu setzen: pdftitle={Foundations of Linear Algebra}.

Leicht übersehen wird, dass diese Felder getrennt vom dokumenteigenen \title und \author sind. Ein \title legt nichts in den Metadaten ab, und eine Änderung der Metadaten verändert die Titelseite nicht. Damit beides zusammenpasst, dient pdfusetitle aus hyperref: Es leitet pdftitle und pdfauthor aus \title und \author ab und beseitigt die doppelte Pflege. Übergeben werden muss es allerdings als Paketoption – \usepackage[pdfusetitle]{hyperref}. Als \hypersetup{pdfusetitle} geschrieben, kommt es nach der Entscheidung und bewirkt gar nichts, ohne Warnung. Enthält der Titel selbst Mathematik oder ein \\, ist wieder \texorpdfstring aus dem vorigen Abschnitt gefragt.

Lesezeichen: die aus den Überschriften gebaute PDF-Gliederung

Lesezeichen – die PDF-Gliederung – sind die einklappbare Überschriftenliste, die ein Betrachter neben der Seite zeigt. Jenseits von hundert Seiten greifen Lesende weit häufiger dazu als zum Inhaltsverzeichnis. hyperref erzeugt sie automatisch aus Kapiteln, Abschnitten und dergleichen (bookmarks=true ist Standard); bookmarksnumbered=true nimmt die Abschnittsnummern auf, bookmarksopen=true zeigt den Baum von Anfang an aufgeklappt. Lesezeichen laufen über eine Hilfsdatei .out und brauchen daher wie das Inhaltsverzeichnis mehr als einen Kompilierlauf, bis sie stabil sind.

Wenn Lesezeichen in komplexen Dokumenten aus dem Ruder laufen – falsche Reihenfolge, zerbrochene Verschachtelung, verschwundene Einträge –, ist das Paket bookmark das übliche Mittel, geladen nach hyperref. Es ersetzt den älteren Lesezeichen-Code von hyperref, stabilisiert den Umgang mit .out und erlaubt zusätzlich, Schriftstärke und Farbe der Einträge festzulegen. Feineinstellungen laufen über \bookmarksetup{...}. Da es praktisch nichts kostet, spricht bei langen Dokumenten nichts dagegen, es von vornherein zu laden.

Wenn Lesezeichen mit Japanisch und anderem Nicht-ASCII zu Zeichensalat werden

Lesezeichen und Metadaten werden als Zeichenketten ins PDF geschrieben; sobald darin Japanisch, Chinesisch, Kyrillisch oder anderes jenseits von ASCII steht, tritt die Kodierung zutage. Entscheidend ist, sie als Unicode auszugeben. Bei LuaLaTeX und XeLaTeX ist unicode standardmäßig aktiv, japanische Lesezeichen erscheinen also üblicherweise ohne Zutun korrekt. Ausdrücklich setzen lässt es sich mit \usepackage[unicode]{hyperref} oder \hypersetup{unicode}.

Der klassische Weg pLaTeX / upLaTeX + dvipdfmx liegt anders. Das Standardrezept lautet \usepackage[dvipdfmx]{hyperref} plus das Paket pxjahyper. pxjahyper gibt es genau dafür: japanische Lesezeichen unter (u)pLaTeX ohne Zeichensalat zu erzeugen; es wird mit TeX Live ausgeliefert. Die zugehörige Option ist pdfencoding=auto, die automatisch entscheidet – Zeichenketten bleiben unverändert, solange sie in ASCII passen, sonst wird auf Unicode umgeschaltet (vor allem für die pdfTeX-Familie; bei Unicode-Engines ist Unicode ohnehin Standard und die Option meist unnötig). Kurz gesagt: bei LuaLaTeX nichts tun, bei (u)pLaTeX pxjahyper ergänzen.

% pLaTeX / upLaTeX + dvipdfmx
\usepackage[dvipdfmx]{hyperref}
\usepackage{pxjahyper}   % Japanese bookmarks without garbling

% LuaLaTeX / XeLaTeX: unicode is already the default
% \usepackage{hyperref}

Verweisbefehle, die hyperref mitbringt: \autoref und \nameref

Neben den Links bringt hyperref zwei Schreibweisen für Verweise mit. \autoref{key} tritt an die Stelle von \ref und stellt automatisch das Wort für die Art des Ziels voran – „section 3.4“ bei einem Abschnitt, „Figure 3“ bei einer Abbildung – und macht das Ganze zum Link. Geändert wird das vorangestellte Wort durch Neudefinition von \figureautorefname, \sectionautorefname und Verwandten; so erfolgt auch die Lokalisierung. Der zweite Befehl, \nameref{key}, fügt keine Nummer ein, sondern den Titeltext selbst: Ein Verweis auf das Label von \section{Introduction} ergibt „Introduction“, was beim Zitieren nach Titel statt nach Nummer gewünscht ist. Werden zusätzlich Mehrfachverweise und automatischer Numerus gebraucht, reicht \cref aus cleveref weiter als \autoref – der vollständige Vergleich steht auf der Seite zu Querverweisen.

Ein \hypersetup, das sich unverändert übernehmen lässt

So sieht die Form aus, auf die sich die meisten Arbeitsdokumente einpendeln. colorlinks=true entfernt die Kästen und färbt den Text, die Farben sind nach Art getrennt, bookmarksnumbered erzeugt nummerierte Lesezeichen, und pdfusetitle hält die Metadaten mit \title und \author im Gleichschritt. Für ein druckorientiertes Dokument werden die vier Zeilen von colorlinks bis urlcolor durch das einzelne Wort hidelinks ersetzt. Die Links sind dann auf der Seite unsichtbar, wer das PDF liest, kann sie aber weiterhin anklicken.

\title{Foundations of Linear Algebra}
\author{A. N. Author}

% pdfusetitle must be a PACKAGE option; inside \hypersetup it does nothing
\usepackage[pdfusetitle]{hyperref}   % almost last
\hypersetup{
  colorlinks=true,       % colour the text, not a box
  linkcolor=blue,        % \ref, \autoref, ToC entries
  citecolor=teal,        % \cite
  urlcolor=magenta,      % \url and \href
  bookmarksnumbered=true,
  pdfsubject={Lecture notes},
  pdfkeywords={LaTeX, linear algebra, vector spaces},
}
\usepackage{bookmark}    % after hyperref: sturdier bookmarks

% print-first alternative: replace the four colour lines with
%   hidelinks,