LaTeX: Cleveref and PDF Bookmarks — A Troubleshooting Guide

This post addresses an issue I encountered when using the cleveref package with hyperref in LaTeX: incorrect rendering of PDF bookmarks when \Cref{} or \cref{} commands are used in section headings.

Background

The hyperref package in LaTeX automatically creates clickable links to referenced labels within a document. The cleveref package enhances this functionality by providing commands like \Cref{} and \cref{}, which print both the label name and its corresponding number as opposed to \ref{}, which only prints the number. Consider the following minimal working example (MWE):

\documentclass{article}
\usepackage{hyperref}
\usepackage{cleveref}

\newtheorem{theorem}{Theorem}

\begin{document}
\section{Introduction}

\begin{theorem}
    \label{thm:my-theorem}
    This is my theorem...
\end{theorem}

\Cref{thm:my-theorem} shows that...
\end{document}

This MWE generates the expected output, where the link to Theorem 1 is clickable:

Problem

The hyperref package also creates PDF bookmarks for the document’s sections, enabling easier navigation in PDF readers. However, when a cleveref command such as \Cref{} is used inside a section title, the resulting bookmark fails to render correctly. Specifically, the label does not appear properly in the bookmark.

To illustrate the issue, wee add the following section to our MWE:

\section{Proof of \Cref{thm:my-theorem}}

This results in the following warning:

Package hyperref Warning: Token not allowed in a PDF string (Unicode): removing \@ifnextchar on input line 17.

Possible Solutions

Two primary solutions can resolve this issue:¹

Solution 1: Using the crossreftools package

This approach involves adding the following lines to your document preamble:

\usepackage{crossreftools}

\pdfstringdefDisableCommands{%
  \let\Cref\crtCref
  \let\cref\crtcref
}

This solution effectively redefines the \Cref{} and \cref{} commands for bookmark generation to ensure compatibility with hyperref’s bookmark generation process. However, it may not function optimally when multiple references are used within a single \Cref{} command.

Solution 2: Manual Override with \texorpdfstring

This method provides a more manual approach. The \texorpdfstring{} command allows you to specify how the section heading should be rendered in the PDF bookmarks. This involves using \ref{} instead of \Cref{} within the \texorpdfstring{} command, as shown below:

\section{Proof of \texorpdfstring{\Cref{thm:my-theorem}}{Theorem~\ref{thm:my-theorem}}}

This command provides two arguments: the first is the text to be displayed in the document, and the second is the text to be used for the PDF bookmark.

Takeaway

In many cases, a combination of both solutions proves to be the most effective approach. By using crossreftools for most instances and manually overriding specific cases with \texorpdfstring{}, you can ensure accurate rendering of both document content and PDF bookmarks.