Hyperlinks (hyperref)

Most LaTeX packages mind their own business. hyperref does not: to turn \ref, \cite, headings and the table of contents into clickable links inside the PDF, it quietly redefines a great many of LaTeX's own commands from the inside. That single fact explains nearly everything else about it — why its manual insists you load it last, why cleveref alone must come after it, and why the red box drawn around every link is the first thing most people switch off. This page covers link appearance, \href and \url, PDF metadata and bookmarks, and the warning you will certainly meet the first time a heading contains mathematics.

What one line of \usepackage{hyperref} turns into a link

Putting \usepackage{hyperref} in the preamble is enough: with no configuration at all, every reference in the document becomes a link. \ref and \pageref, citations made with \cite, each entry in the table of contents and the lists of figures and tables, footnote marks, index entries — anything whose destination can be pinned down. Click one in a PDF viewer and you land on the target; a URL opens in the browser. Sometimes, though, you do not want the link. The referencing commands come in starred forms: \ref*{key}, \pageref*{key} and \autoref*{key} print the number without making it clickable.

Why hyperref is loaded last, and the one exception

hyperref belongs almost last in the preamble, for the reason given at the top: this package's job is to redefine a great many LaTeX commands. Load some other package that touches the same commands afterwards and those redefinitions are overwritten, quietly breaking links and bookmarks. The hyperref manual states this advice plainly, and attaches a footnote to it noting that work has begun to cut down the number of redefinitions and with it the dependence on load order. So this is a present-day workaround rather than a permanent law of nature — package load order in general is covered on the document class and preamble page.

There is effectively one exception to “last”: cleveref. It builds its own referencing commands by detecting what hyperref has defined, so the reverse order cannot work. This does not fail silently — the cleveref.sty shipped with TeX Live 2024 checks the order at \begin{document} and stops with ! Package cleveref Error: cleveref must be loaded after hyperref!. If varioref is in play too, the order is varioref → hyperref → cleveref. One further thing the manual forbids outright: do not load hyperref inside \AtBeginDocument or the begindocument hook, because hyperref and nameref use that hook themselves and the timing becomes fragile. If loading must be delayed, the hook to use is 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 and hidelinks: getting rid of the red box

Out of the box, hyperref marks a link by drawing a coloured box around it (colorlinks defaults to false). On screen that is admittedly easy to spot; on paper it is a problem, because the box prints while the link does not exist there at all. The reader is left with red rectangles scattered through the text serving no visible purpose — which is precisely what people mean when they say hyperref “ruined the look” of their document. You configure this either with options at load time or afterwards through \hypersetup{...}, listing key=value pairs separated by commas. \hypersetup may sit anywhere in the preamble.

The first thing most people set is colorlinks=true. It drops the box and colours the link text itself, which prints cleanly and reads well on screen. The colours are per kind, and the defaults are red for linkcolor, green for citecolor, magenta for urlcolor and cyan for filecolor — a scheme designed to be told apart on a monitor, and rather loud in a submitted paper. To calm it down quickly, allcolors sets them all to one value; for print-first work the answer is hidelinks, which applies neither colour nor border so the links become visually invisible while staying clickable. That last combination suits the common case best: a document distributed as PDF but also read on paper.

\href and \url: linking to the outside world

Links to external URLs come from two commands. \href{URL}{display text} attaches a link to any words you like; \url{URL} typesets the URL itself in a monospaced font and makes it a link at the same time. Use \url when the address should be visible in the text and \href when it should hide behind other words. What makes them worth the trouble is how they treat their argument: LaTeX special characters that URLs are full of — %, #, ~, _ — can be written literally in the URL part, with no escaping (a few restrictions remain inside the argument of \url). If you want the monospaced look but no link at all, use \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, and \texorpdfstring

Put mathematics in a heading and hyperref will almost certainly produce this warning. The cause is that a heading's text has two destinations: the typeset heading in the body, and a plain string in the PDF bookmarks. A bookmark is, by the PDF specification, nothing but text, so a $, a ^ or a command like \emph cannot go into it. hyperref discards each token it cannot use and reports what it dropped, one message at a time. The heading itself still typesets correctly; only the bookmark loses its contents — which is exactly the quiet degradation you get by ignoring the warning.

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.

The fix is \texorpdfstring{for TeX}{for the PDF string}. The first argument is used for typesetting and the second for the bookmark, so you can hand the heading its mathematics and the bookmark a spoken-out version: \section{The value of \texorpdfstring{$x^2$}{x squared}}. One catch deserves attention: the second argument becomes a PDF string as well, so writing x^2 there simply moves the warning to the ^. Leave no markup in it — put characters only, such as x squared or the Unicode x².

PDF metadata: pdftitle, pdfauthor and pdfusetitle

hyperref also writes the PDF's document information — the fields shown under “Document Properties” in a viewer, the ones a reference manager imports and many search indexes read. You set them through \hypersetup with pdftitle (title), pdfauthor (author), pdfsubject (subject) and pdfkeywords (keywords). A value containing a comma or an equals sign collides with the key separators, so it is safest to wrap values in braces: pdftitle={Foundations of Linear Algebra}.

What people miss is that these are separate from the document's own \title and \author. Writing \title puts nothing into the metadata, and editing the metadata changes nothing on the title page. To keep the two in step, use hyperref's pdfusetitle, which derives pdftitle and pdfauthor from \title and \author and removes the duplicated bookkeeping. It has to be given as a package option, though — \usepackage[pdfusetitle]{hyperref}. Written as \hypersetup{pdfusetitle} it arrives after the decision has been made and does nothing at all, without a warning. If the title itself contains mathematics or a \\, you are back to \texorpdfstring from the previous section.

Bookmarks: the PDF outline built from your headings

Bookmarks — the PDF outline — are the collapsible list of headings a viewer shows beside the page. Past a hundred pages, readers reach for it far more often than for the table of contents. hyperref generates it automatically from the document's chapters, sections and so on (bookmarks=true is the default); add bookmarksnumbered=true to include section numbers and bookmarksopen=true to show the tree expanded from the start. Bookmarks travel through an auxiliary .out file, so like the table of contents they need more than one compilation before they settle.

When bookmarks misbehave in a complex document — wrong order, broken nesting, entries that vanish — the standard remedy is the bookmark package, loaded after hyperref. It replaces hyperref's older bookmark code, stabilises how .out is handled, and additionally lets you set the weight and colour of bookmark entries. Fine adjustments go through \bookmarksetup{...}. It costs essentially nothing, so in a long document there is no reason not to load it from the start.

When bookmarks come out garbled in Japanese and other non-ASCII text

Bookmarks and metadata are written into the PDF as strings, so encoding surfaces the moment those strings contain Japanese, Chinese, Cyrillic or anything else beyond ASCII. The key is to emit them as Unicode. On LuaLaTeX and XeLaTeX, unicode is enabled by default, so bookmarks in Japanese normally come out right with nothing added. To be explicit, write \usepackage[unicode]{hyperref} or \hypersetup{unicode}.

The traditional pLaTeX / upLaTeX + dvipdfmx route is a different story. The standard recipe is \usepackage[dvipdfmx]{hyperref} plus the pxjahyper package. pxjahyper exists precisely to produce Japanese bookmarks without garbling under (u)pLaTeX, and it ships with TeX Live. The related option is pdfencoding=auto, which decides automatically: leave strings alone when they fit in ASCII, switch to Unicode when they do not (mainly for the pdfTeX family; on Unicode engines Unicode is already the default, so it is usually unnecessary). In short: nothing to do on LuaLaTeX; add pxjahyper on (u)pLaTeX.

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

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

Reference commands hyperref adds: \autoref and \nameref

Along with the links, hyperref adds two ways of writing a reference. \autoref{key} replaces \ref and prepends the word for the target's kind automatically — “section 3.4” for a section, “Figure 3” for a figure — making the whole thing a link. The prepended word is changed by redefining \figureautorefname, \sectionautorefname and their relatives, which is also how you localise it. The other, \nameref{key}, inserts not a number but the title text itself: reference the label on \section{Introduction} and you get “Introduction”, which is what you want when citing by title rather than by number. If you also need multiple references and automatic plurals, cleveref's \cref goes further than \autoref — the full comparison lives on the cross-references page.

A \hypersetup you can copy as it stands

Here is the shape most working documents settle into. colorlinks=true drops the boxes and colours the text, the colours are separated by kind, bookmarksnumbered builds numbered bookmarks, and pdfusetitle keeps the metadata in step with \title and \author. For a print-first document, replace the four lines from colorlinks through urlcolor with the single word hidelinks. The links then become invisible on the page while anyone reading the PDF still gets to click them.

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