Hyperliens (hyperref)

La plupart des paquets LaTeX se mêlent de leurs affaires. hyperref, non : pour transformer \ref, \cite, les titres et la table des matières en liens cliquables dans le PDF, il redéfinit discrètement, de l'intérieur, un grand nombre de commandes propres à LaTeX. Ce seul fait explique presque tout le reste — pourquoi son manuel insiste pour qu'on le charge en dernier, pourquoi cleveref seul doit venir après lui, et pourquoi le cadre rouge tracé autour de chaque lien est la première chose que la plupart désactivent. Cette page traite de l'apparence des liens, de \href et \url, des métadonnées et signets PDF, et de l'avertissement que l'on rencontre immanquablement dès qu'un titre contient des mathématiques.

Ce qu'une ligne de \usepackage{hyperref} transforme en liens

Écrire \usepackage{hyperref} dans le préambule suffit : sans la moindre configuration, chaque renvoi du document devient un lien. \ref et \pageref, les citations faites avec \cite, chaque entrée de la table des matières et des listes de figures et de tableaux, les appels de note, les entrées d'index — tout ce dont la destination peut être déterminée. Un clic dans un lecteur PDF mène à la cible ; une URL s'ouvre dans le navigateur. Il arrive pourtant que le lien soit indésirable. Les commandes de renvoi existent donc en forme étoilée : \ref*{key}, \pageref*{key} et \autoref*{key} impriment le numéro sans le rendre cliquable.

Pourquoi charger hyperref en dernier, et la seule exception

hyperref se place presque en dernier dans le préambule, pour la raison donnée en tête : le travail de ce paquet consiste à redéfinir un très grand nombre de commandes LaTeX. Charger ensuite un autre paquet qui touche aux mêmes commandes écrase ces redéfinitions, et liens comme signets se brisent en silence. Le manuel d'hyperref énonce ce conseil sans détour et y accroche une note précisant qu'un travail a commencé pour réduire le nombre de redéfinitions, et donc la dépendance à l'ordre de chargement. Il s'agit donc d'un contournement actuel, non d'une loi définitive — l'ordre de chargement en général est traité sur la page consacrée à la classe de document et au préambule.

À « en dernier » il n'existe en pratique qu'une exception : cleveref. Il construit ses propres commandes de renvoi en détectant ce qu'a défini hyperref ; l'ordre inverse ne peut pas fonctionner. L'échec n'est pas silencieux : le cleveref.sty livré avec TeX Live 2024 vérifie l'ordre à \begin{document} et s'arrête sur ! Package cleveref Error: cleveref must be loaded after hyperref!. Si varioref entre aussi en jeu, l'ordre est varioref → hyperref → cleveref. Le manuel proscrit encore autre chose : ne chargez pas hyperref à l'intérieur de \AtBeginDocument ni du hook begindocument, car hyperref et nameref utilisent eux-mêmes ce hook et la chronologie devient fragile. Si le chargement doit être différé, le hook à employer est begindocument/before.

\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 et hidelinks : se débarrasser du cadre rouge

Par défaut, hyperref signale un lien en traçant autour de lui un cadre coloré (colorlinks vaut false). À l'écran, c'est certes bien visible ; sur papier, cela pose problème, car le cadre s'imprime alors que le lien n'existe pas là. Restent des rectangles rouges dispersés dans le texte sans utilité apparente — c'est exactement ce que veulent dire ceux qui affirment qu'hyperref a « abîmé » leur mise en page. La configuration passe soit par les options au chargement, soit ensuite par \hypersetup{...}, en listant des paires key=value séparées par des virgules. \hypersetup peut figurer n'importe où dans le préambule.

Le premier réglage que l'on pose est généralement colorlinks=true. Il supprime le cadre et colore le texte du lien lui-même : le rendu imprimé reste propre et la lecture à l'écran agréable. Les couleurs sont réparties par type, avec pour valeurs par défaut le rouge pour linkcolor, le vert pour citecolor, le magenta pour urlcolor et le cyan pour filecolor — un jeu pensé pour se distinguer sur un écran, plutôt criard dans un article soumis. Pour l'assagir vite, allcolors les fixe toutes à une même valeur ; pour un travail destiné d'abord au papier, la réponse est hidelinks : ni couleur ni cadre, les liens deviennent visuellement invisibles tout en restant cliquables. Cette dernière combinaison convient au cas le plus courant : un document diffusé en PDF mais lu aussi sur papier.

\href et \url : les liens vers l'extérieur

Les liens vers des URL externes viennent de deux commandes. \href{URL}{display text} attache un lien aux mots de votre choix ; \url{URL} compose l'URL elle-même en chasse fixe et en fait un lien du même geste. On prend \url quand l'adresse doit rester visible dans le texte, \href quand elle doit se dissimuler derrière d'autres mots. Ce qui fait leur valeur, c'est le traitement de l'argument : les caractères spéciaux de LaTeX dont les URL regorgent — %, #, ~, _ — s'écrivent littéralement dans la partie URL, sans échappement (quelques restrictions subsistent dans l'argument de \url). Pour l'aspect à chasse fixe sans aucun lien, on utilise \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 et \texorpdfstring

Dès qu'un titre contient des mathématiques, hyperref produit presque à coup sûr cet avertissement. La raison : le texte d'un titre a deux destinations — le titre composé dans le corps, et une chaîne brute dans les signets du PDF. Un signet n'est, selon la spécification PDF, que du texte : un $, un ^ ou une commande comme \emph ne peuvent pas y figurer. hyperref écarte chaque jeton inutilisable et signale un par un ce qu'il a supprimé. Le titre lui-même reste correctement composé ; seul le signet perd son contenu — précisément la dégradation silencieuse qu'on obtient en ignorant l'avertissement.

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.

La solution s'appelle \texorpdfstring{pour TeX}{pour la chaîne PDF}. Le premier argument sert à la composition, le second au signet : le titre reçoit ses mathématiques, le signet une version énoncée — \section{The value of \texorpdfstring{$x^2$}{x squared}}. Une subtilité mérite attention : le second argument devient lui aussi une chaîne PDF, si bien qu'y écrire x^2 ne fait que déplacer l'avertissement sur le ^. N'y laissez aucun balisage : des caractères seulement, comme x squared ou le x² Unicode.

Métadonnées PDF : pdftitle, pdfauthor et pdfusetitle

hyperref écrit aussi les informations de document du PDF — les champs affichés sous « Propriétés du document » dans un lecteur, ceux qu'importe un gestionnaire de références et que lisent bien des index de recherche. On les définit via \hypersetup avec pdftitle (titre), pdfauthor (auteur), pdfsubject (sujet) et pdfkeywords (mots-clés). Une valeur contenant une virgule ou un signe égal entre en conflit avec les séparateurs de clés : le plus sûr est donc d'entourer les valeurs d'accolades, pdftitle={Foundations of Linear Algebra}.

Ce qui échappe souvent, c'est que ces champs sont distincts du \title et de l'\author du document. Écrire \title ne dépose rien dans les métadonnées, et modifier les métadonnées ne change rien à la page de titre. Pour synchroniser les deux, on emploie pdfusetitle d'hyperref : il fait dériver pdftitle et pdfauthor de \title et \author et supprime la double tenue de comptes. Encore faut-il le passer en option de paquet — \usepackage[pdfusetitle]{hyperref}. Écrit sous la forme \hypersetup{pdfusetitle}, il arrive après la décision et ne fait absolument rien, sans le moindre avertissement. Si le titre contient lui-même des mathématiques ou un \\, on revient à \texorpdfstring de la section précédente.

Signets : le plan du PDF construit à partir des titres

Les signets — le plan du PDF — forment la liste repliable de titres qu'un lecteur affiche à côté de la page. Au-delà de cent pages, on y recourt bien plus souvent qu'à la table des matières. hyperref les engendre automatiquement à partir des chapitres, sections et autres (bookmarks=true par défaut) ; bookmarksnumbered=true y ajoute les numéros de section, bookmarksopen=true affiche l'arborescence déjà déployée. Les signets transitent par un fichier auxiliaire .out : comme la table des matières, ils réclament plus d'une compilation avant de se stabiliser.

Quand les signets déraillent dans un document complexe — ordre faux, imbrication cassée, entrées disparues —, le remède habituel est le paquet bookmark, chargé après hyperref. Il remplace l'ancien code de signets d'hyperref, stabilise le traitement du .out et permet en outre de régler la graisse et la couleur des entrées. Les ajustements fins passent par \bookmarksetup{...}. Comme il ne coûte pratiquement rien, rien n'empêche de le charger d'emblée dans un long document.

Quand les signets sortent illisibles en japonais et autres textes non ASCII

Signets et métadonnées sont écrits dans le PDF sous forme de chaînes : dès que ces chaînes contiennent du japonais, du chinois, du cyrillique ou quoi que ce soit au-delà de l'ASCII, l'encodage se manifeste. La clé est de les émettre en Unicode. Avec LuaLaTeX et XeLaTeX, unicode est actif par défaut : les signets en japonais sortent donc normalement corrects sans rien ajouter. Pour l'expliciter, on écrit \usepackage[unicode]{hyperref} ou \hypersetup{unicode}.

La voie traditionnelle pLaTeX / upLaTeX + dvipdfmx obéit à d'autres règles. La recette standard est \usepackage[dvipdfmx]{hyperref} accompagné du paquet pxjahyper. pxjahyper existe précisément pour produire des signets japonais sans texte illisible sous (u)pLaTeX, et il est livré avec TeX Live. L'option apparentée est pdfencoding=auto, qui tranche automatiquement : les chaînes restent telles quelles tant qu'elles tiennent en ASCII, sinon le passage à Unicode s'opère (surtout pour la famille pdfTeX ; sur les moteurs Unicode, Unicode est déjà la valeur par défaut et l'option est le plus souvent inutile). En résumé : rien à faire avec LuaLaTeX ; ajouter pxjahyper avec (u)pLaTeX.

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

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

Les commandes de renvoi qu'ajoute hyperref : \autoref et \nameref

En même temps que les liens, hyperref ajoute deux façons d'écrire un renvoi. \autoref{key} remplace \ref et préfixe automatiquement le mot du type de cible — « section 3.4 » pour une section, « Figure 3 » pour une figure — en faisant de l'ensemble un lien. Ce mot se change en redéfinissant \figureautorefname, \sectionautorefname et leurs parents ; c'est aussi la voie de la localisation. L'autre, \nameref{key}, insère non pas un numéro mais le texte du titre lui-même : renvoyer à l'étiquette de \section{Introduction} donne « Introduction », ce qu'on veut quand on cite par titre et non par numéro. Si des renvois multiples et des pluriels automatiques sont aussi nécessaires, \cref de cleveref va plus loin qu'\autoref — la comparaison complète figure sur la page des renvois.

Un \hypersetup à recopier tel quel

Voici la forme sur laquelle se stabilisent la plupart des documents de travail. colorlinks=true supprime les cadres et colore le texte, les couleurs sont séparées par type, bookmarksnumbered crée des signets numérotés, et pdfusetitle maintient les métadonnées au diapason de \title et \author. Pour un document destiné d'abord au papier, remplacez les quatre lignes de colorlinks à urlcolor par le seul mot hidelinks. Les liens deviennent alors invisibles sur la page, tandis que quiconque lit le PDF peut toujours cliquer.

\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,