Hyperref

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: igbuend
• Source: igbuend/grimbard
• License: MIT

Install and usage instructions live in the source repository linked above.