hyperref — Hyperlinks, Cross-References & PDF Metadata

CTAN: https://ctan.org/pkg/hyperref
Manual: texdoc hyperref

Setup

% LOAD HYPERREF LAST (or near last) — it redefines many commands
\usepackage[
  colorlinks=true,
  linkcolor=blue,
  citecolor=green!50!black,
  urlcolor=blue!70!black,
  pdftitle={My Document Title},
  pdfauthor={Author Name},
]{hyperref}

% If using cleveref, load it AFTER hyperref:
\usepackage{cleveref}

Common Setup Options

Option	Default	Description
colorlinks	false	Color link text (vs boxes)
linkcolor	red	Internal links (refs, TOC)
citecolor	green	Citation links
urlcolor	magenta	URL links
filecolor	cyan	File links
allcolors	—	Set all link colors at once
hidelinks	—	No color, no boxes (for print)
bookmarks	true	Generate PDF bookmarks
bookmarksnumbered	false	Include section numbers in bookmarks
bookmarksopen	false	Expand bookmarks by default
pdfborder	{0 0 1}	Link border (set {0 0 0} to remove)
breaklinks	true	Allow links to break across lines
unicode	true (modern)	Unicode in bookmarks

PDF Metadata Options

Option	Description
pdftitle	Document title
pdfauthor	Author name(s)
pdfsubject	Subject
pdfkeywords	Keywords (comma-separated)
pdfcreator	Creating application
pdfproducer	PDF producer

% Or set after loading:
\hypersetup{
  pdftitle={My Paper},
  pdfauthor={Jane Doe},
  pdfsubject={LaTeX Tutorial},
  pdfkeywords={LaTeX, hyperref, tutorial},
}

Link Commands

% External URL
\href{https://example.com}{Click here}
\href{mailto:user@example.com}{Email me}
\href{file:./report.pdf}{Local file}

% URL (typewriter, breakable)
\url{https://example.com/path?query=value}

% Internal reference with custom text
\hyperref[sec:intro]{see the introduction}

% Standard cross-references (auto-linked by hyperref)
\ref{fig:plot}        % "3"
\pageref{tab:data}    % "12"
\eqref{eq:main}       % "(1)" — from amsmath

% Auto-named references
\autoref{fig:plot}     % "Figure 3"
\autoref{tab:data}     % "Table 2"
\autoref{sec:intro}    % "section 1"
\autoref{eq:main}      % "equation 1"

% Name reference (prints the title/caption)
\nameref{sec:intro}    % "Introduction"

\autoref Names

Counter	Default name
figure	Figure
table	Table
equation	equation
section	section
chapter	chapter
theorem	Theorem
page	page

Customize: \renewcommand{\sectionautorefname}{Section}

cleveref Integration

\usepackage{hyperref}
\usepackage{cleveref}   % MUST be after hyperref

% Automatic type detection + ranges
\cref{fig:a}              % "fig. 1"
\Cref{fig:a}              % "Figure 1" (capitalized)
\cref{fig:a,fig:b,fig:c}  % "figs. 1 to 3"
\cref{eq:1,eq:2}          % "eqs. (1) and (2)"
\crefrange{fig:a}{fig:d}  % "figs. 1 to 4"

% Customize names
\crefname{equation}{eq.}{eqs.}
\Crefname{equation}{Equation}{Equations}
\crefname{figure}{fig.}{figs.}

Bookmarks

% Manual bookmark entry
\pdfbookmark[level]{Text}{anchor}
\pdfbookmark[0]{Title Page}{title}

% Current bookmark (without section command)
\currentpdfbookmark{Appendix A}{appendixA}

% Bookmark with section:
\belowpdfbookmark{Subsection text}{anchor}  % below current level

Link Appearance

% Colored text links (preferred for screen)
\hypersetup{colorlinks=true, allcolors=blue}

% Boxed links (default)
\hypersetup{colorlinks=false, pdfborder={0 0 1}}

% Hidden links (for print)
\hypersetup{hidelinks}

% Custom: colored + no underline
\hypersetup{
  colorlinks=true,
  linkcolor={blue!80!black},
  citecolor={green!60!black},
  urlcolor={red!70!black},
}

Common Patterns

Clickable TOC with Print-Friendly Style

\usepackage[
  colorlinks=true,
  linkcolor=black,      % TOC/internal links in black
  citecolor=blue!50!black,
  urlcolor=blue!70!black,
  bookmarks=true,
  bookmarksnumbered=true,
]{hyperref}

Thesis/Dissertation Setup

\usepackage[
  hidelinks,            % clean for printing
  bookmarks=true,
  bookmarksnumbered=true,
  bookmarksopen=true,
  bookmarksopenlevel=2,
  pdftitle={PhD Thesis},
  pdfauthor={Name},
]{hyperref}
\usepackage{cleveref}

Back-References in Bibliography

\usepackage[backref=page]{hyperref}
% Adds "Cited on page(s) X, Y" to bibliography entries

Common Pitfalls

Problem	Cause	Fix
Broken cross-references	hyperref loaded too early	Load hyperref last (before cleveref)
\autoref says "section" lowercase	Default names	\renewcommand{\sectionautorefname}{Section}
Bookmark errors with math	Math in section titles	\texorpdfstring{$E=mc^2$}{E=mc2}
"Token not allowed"	Special chars in PDF strings	Use \texorpdfstring{LaTeX}{LaTeX}
Links in headers/footers	Fragile commands	Use \protect or \texorpdfstring
cleveref not working	Loaded before hyperref	Load order: hyperref → cleveref
Link boxes overlap text	Default border style	Use colorlinks=true or hidelinks
\url breaks wrong	Long URLs	hyperref handles this; check breaklinks=true
Conflicts with other packages	Package redefines same commands	Load hyperref after most packages

Load Order Guide

% Safe order (most common packages):
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{...}          % other packages
\usepackage[options]{hyperref}  % near last
\usepackage{cleveref}           % very last

Tips

• Always use colorlinks for screen PDFs; hidelinks for print
• \texorpdfstring{LaTeX version}{plain text} for anything fancy in section titles
• \phantomsection before \addcontentsline for correct hyperlinks in unnumbered sections
• \hypersetup{} can be called multiple times to change settings mid-document
• Use \nohyperpage in index entries to prevent hyperref page linking