Cleveref And Hyperref: Best Practices For Compatibility
The Core Issue: Conflicting Counter Reset
Cleveref and hyperref are two popular LaTeX packages that enhance cross-referencing capabilities. However, they can conflict with each other if not used properly. The core issue is that cleveref resets counters when defining new environments, while hyperref steps counter values when creating anchors for hyperlinks. This leads to incorrectly incremented reference labels when cleveref and hyperref are used together without compatible settings.
Cleveref Refresher
How cleveref works: alias, types, formats
The cleveref package allows authors to easily customize cross-reference names and formats without coding complex commands. Some key features:
- Automatic aliasing of reference types (e.g. section becomes "section" or "sec.")
- Formatting control for capitalization, punctuation, compression
- Multi-reference capability (e.g. Figs 1, 3 and 4)
Cleveref is highly configurable for the document classes, environments, and reference types an author needs. For example, the package can recognize custom theorem-like environments to refer to as "Theorem" or "lemma."
Resetting counters for new environments
A key part of how cleveref works is that it resets counter values for defined environments. This helps ensure accurate linking between reference anchors and counter printouts. For instance, a new chapter would reset the equation counter, enabling \cref to reference Equation 1 in Chapter 1 and Equation 1 in Chapter 2 unambiguously. This counter reset causes issues with hyperref's stepped counters that cleveref usage must address.
Hyperref Refresher
How hyperref enhances cross-references
The hyperref package gives cross-references special abilities like:
- Hyperlinks for easy navigation
- PDF bookmarks to supplement hyperlinks
- Back-references after each \label to return from citations
These features require hyperref to manipulate counters in ways that cleveref may not expect. The key issue is hyperref’s counter step rather than reset.
Stepping counter values when creating anchors
Hyperref increments counter values such as section or footnote numbers at every \label anchor. This allows each reference target to have a unique ID for linking. However, the stepped counters get out of sync with cleveref’s resets. A reference cleveref expects to show “1” may display “3” if hyperref has stepped the counter twice already. The solution is making cleveref work with hyperref’s approach.
Best Practices
Load order matters
The first best practice is to load hyperref before cleveref in the document preamble. This ensures cleveref sees hyperref’s setup and makes compatible settings. If cleveref loads first, issues can still emerge later.
Set hyperref to use Cleveref
The second step is explicitly telling hyperref that cleveref manages counters. This prevents hyperref from blindly incrementing counters that cleveref needs at consistent values. The command is:
\usepackage[hyperref]{cleveref}
Used immediately after loading hyperref. This single line eliminates almost all conflicts between the packages.
Example code
\usepackage{hyperref}
\usepackage[hyperref]{cleveref}
\usepackage{cleveref}
Followed by normal cleveref and hyperref customizations after the setup. Now cleveref and hyperref will work in harmony rather than competing.
Special Cases
With the above practices, cleveref and hyperref cooperate for most standard docs. A few cases require extra effort, however.
Tables and figures
Tables and figures have their own counter tracking separate from “section” or “equation.” As a result, the hyperref-cleveref directive only resolves issues with main counters like chapter/section/page. Special handling for cref’s table and figure integration includes:
- Running \crefname and \Crefname to reset anchors
- Manual counter value saves+\restores when needed
This takes some coding work but lets cref fully manage special environments.
Listings environment
The LaTeX listings package for code snippets provides a “listings” environment with custom parameters. Like tables and figures, listings needs explicit synchronization handling:
\counterwithin{lstlisting}{section}
\creflabelformat{lstlisting}{#2#1#3}
Primarily to nest listings counters under sections to match cleveref expectations.
Undefined references
Random errors can occur for unusual cases like undefined references from older Tex builds. Debugging obscure issues requires confirmation of up-to-date distributions for:
- TeX Live/MiKTeX core
- All document class files
- Cleveref and hyperref packages
Eliminating ambiguities from outdated modules streamlines troubleshooting.
Additional Tips
Some extra recommendations for special use cases.
Disable hyperref for some refs
At times, the hyperlinking behavior causes issues for a cleveref application. In these rare cases, hyperref can be disabled locally:
{\hyperref[off]} % Turn off
\cref{...} % Non-hyper cref
{\hyperref[on]} % Restore hyperref
Not recommended for routine use but available if needed.
Customization options
Take full advantage of prefixes, aliases, capitalization, and formats for custom reference outputs. For example:
\crefrangeformat{equation}{(#3#1#4) to (#5#2#6)}
\Crefformat{section}{Section~#2#1#3}
This adds specialized outputs without much coding work.
Summary
In summary, cleveref and hyperref are powerful packages for references and links. Use compatible settings with hyperref first, then cleveref directed at hyperref counters for best results. Handle special cases like tables and listings carefully within this framework. Follow best practices and these packages will enhance document authoring and reading experiences.
