Hipervínculos (hyperref)

La mayoría de los paquetes de LaTeX se ocupan de lo suyo. hyperref no: para convertir \ref, \cite, los encabezados y el índice en enlaces clicables dentro del PDF, redefine calladamente, desde dentro, un buen número de comandos propios de LaTeX. Ese único hecho explica casi todo lo demás: por qué su manual insiste en cargarlo el último, por qué solo cleveref debe ir después de él, y por qué el recuadro rojo dibujado alrededor de cada enlace es lo primero que casi todos desactivan. Esta página cubre el aspecto de los enlaces, \href y \url, los metadatos y marcadores del PDF, y la advertencia que aparece sin falta la primera vez que un encabezado contiene matemáticas.

Qué convierte en enlace una línea de \usepackage{hyperref}

Basta con poner \usepackage{hyperref} en el preámbulo: sin configuración alguna, cada referencia del documento se vuelve un enlace. \ref y \pageref, las citas hechas con \cite, cada entrada del índice y de las listas de figuras y tablas, las llamadas de nota, las entradas del índice alfabético: todo aquello cuyo destino puede fijarse. Un clic en un visor PDF lleva al destino; una URL se abre en el navegador. A veces, sin embargo, el enlace estorba. Los comandos de referencia existen en forma con asterisco: \ref*{key}, \pageref*{key} y \autoref*{key} imprimen el número sin hacerlo clicable.

Por qué hyperref se carga el último, y la única excepción

hyperref va casi al final del preámbulo, por la razón dada al principio: la tarea de este paquete es redefinir un gran número de comandos de LaTeX. Si después se carga otro paquete que toca esos mismos comandos, sus redefiniciones quedan sobrescritas y enlaces y marcadores se rompen en silencio. El manual de hyperref formula este consejo sin rodeos y le añade una nota indicando que se ha empezado a reducir el número de redefiniciones y, con ello, la dependencia del orden de carga. Se trata, pues, de un apaño actual y no de una ley permanente; el orden de carga en general se trata en la página sobre clase de documento y preámbulo.

A ese “el último” le corresponde en la práctica una sola excepción: cleveref. Construye sus propios comandos de referencia detectando lo que hyperref ha definido, así que el orden inverso no puede funcionar. El fallo no es silencioso: el cleveref.sty que trae TeX Live 2024 comprueba el orden en \begin{document} y se detiene con ! Package cleveref Error: cleveref must be loaded after hyperref!. Si varioref también interviene, el orden es varioref → hyperref → cleveref. El manual prohíbe además otra cosa: no cargue hyperref dentro de \AtBeginDocument ni del hook begindocument, porque hyperref y nameref usan ese hook y la sincronización se vuelve frágil. Si hay que retrasar la carga, el hook adecuado es 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 y hidelinks: deshacerse del recuadro rojo

De serie, hyperref señala un enlace dibujando a su alrededor un recuadro de color (colorlinks vale false por defecto). En pantalla se localiza bien, es cierto; en papel se convierte en un problema, porque el recuadro se imprime mientras que el enlace no existe allí. Quedan rectángulos rojos repartidos por el texto sin utilidad visible, que es justo lo que quiere decir quien afirma que hyperref le “estropeó” la maqueta. La configuración se hace con opciones al cargar el paquete o después mediante \hypersetup{...}, listando pares key=value separados por comas. \hypersetup puede ir en cualquier punto del preámbulo.

Lo primero que casi todos configuran es colorlinks=true. Elimina el recuadro y colorea el propio texto del enlace, lo que imprime limpio y se lee bien en pantalla. Los colores van por tipo, y los valores por defecto son rojo para linkcolor, verde para citecolor, magenta para urlcolor y cian para filecolor: un esquema pensado para distinguirse en un monitor y bastante estridente en un artículo enviado a revista. Para calmarlo deprisa, allcolors los fija todos en un mismo valor; para trabajo orientado a la imprenta la respuesta es hidelinks, que no aplica ni color ni borde, de modo que los enlaces se vuelven visualmente invisibles pero siguen siendo clicables. Esta última combinación encaja con el caso más común: un documento distribuido en PDF que también se lee en papel.

\href y \url: enlazar con el mundo exterior

Los enlaces a URL externas provienen de dos comandos. \href{URL}{display text} adjunta un enlace a las palabras que se quiera; \url{URL} compone la propia URL en letra monoespaciada y la convierte en enlace a la vez. Se usa \url cuando la dirección debe verse en el texto y \href cuando debe esconderse tras otras palabras. Su valor está en cómo tratan el argumento: los caracteres especiales de LaTeX de los que las URL están llenas —%, #, ~, _— pueden escribirse literalmente en la parte de la URL, sin escapar (quedan algunas restricciones dentro del argumento de \url). Si se quiere el aspecto monoespaciado pero ningún enlace, se usa \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 y \texorpdfstring

En cuanto un encabezado contiene matemáticas, hyperref produce casi con seguridad esta advertencia. El motivo: el texto de un encabezado tiene dos destinos, el encabezado compuesto en el cuerpo y una cadena en bruto en los marcadores del PDF. Un marcador, según la especificación PDF, no es más que texto, así que un $, un ^ o un comando como \emph no caben ahí. hyperref descarta cada token inservible e informa uno por uno de lo que ha eliminado. El encabezado sigue componiéndose bien; solo el marcador pierde su contenido, que es justo la degradación silenciosa que se obtiene al ignorar el aviso.

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.

La solución es \texorpdfstring{para TeX}{para la cadena PDF}. El primer argumento se usa para componer y el segundo para el marcador, de modo que el encabezado recibe sus matemáticas y el marcador una versión enunciada: \section{The value of \texorpdfstring{$x^2$}{x squared}}. Un detalle merece atención: el segundo argumento también se convierte en cadena PDF, así que escribir allí x^2 solo traslada la advertencia al ^. No deje marcado alguno: solo caracteres, como x squared o el x² de Unicode.

Metadatos del PDF: pdftitle, pdfauthor y pdfusetitle

hyperref escribe además la información de documento del PDF: los campos que aparecen bajo “Propiedades del documento” en un visor, los que importa un gestor de referencias y los que leen muchos índices de búsqueda. Se definen mediante \hypersetup con pdftitle (título), pdfauthor (autor), pdfsubject (asunto) y pdfkeywords (palabras clave). Un valor con coma o signo igual choca con los separadores de claves, así que lo más seguro es encerrar los valores entre llaves: pdftitle={Foundations of Linear Algebra}.

Lo que suele pasarse por alto es que estos campos son distintos del \title y el \author del propio documento. Escribir \title no deja nada en los metadatos, y editar los metadatos no cambia nada en la portada. Para mantenerlos sincronizados se emplea pdfusetitle de hyperref, que deriva pdftitle y pdfauthor de \title y \author y suprime la doble contabilidad. Eso sí, hay que darlo como opción del paquete: \usepackage[pdfusetitle]{hyperref}. Escrito como \hypersetup{pdfusetitle} llega después de que la decisión se haya tomado y no hace absolutamente nada, sin advertencia alguna. Si el título contiene matemáticas o un \\, se vuelve a \texorpdfstring de la sección anterior.

Marcadores: el esquema del PDF construido con los encabezados

Los marcadores —el esquema del PDF— son la lista plegable de encabezados que un visor muestra junto a la página. Pasadas las cien páginas, se recurre a ella mucho más que al índice. hyperref la genera automáticamente a partir de capítulos, secciones y demás (bookmarks=true por defecto); bookmarksnumbered=true incluye los números de sección y bookmarksopen=true muestra el árbol ya desplegado. Los marcadores pasan por un archivo auxiliar .out, así que, igual que el índice, exigen más de una compilación antes de asentarse.

Cuando los marcadores se descarrían en un documento complejo —orden equivocado, anidamiento roto, entradas que desaparecen—, el remedio habitual es el paquete bookmark, cargado después de hyperref. Sustituye el código antiguo de marcadores de hyperref, estabiliza el manejo del .out y además permite fijar el grosor y el color de las entradas. Los ajustes finos pasan por \bookmarksetup{...}. Como no cuesta prácticamente nada, en un documento largo no hay razón para no cargarlo desde el principio.

Cuando los marcadores salen ilegibles con japonés y otros textos no ASCII

Los marcadores y los metadatos se escriben en el PDF como cadenas, de modo que la codificación aflora en cuanto esas cadenas contienen japonés, chino, cirílico o cualquier cosa más allá del ASCII. La clave es emitirlas como Unicode. En LuaLaTeX y XeLaTeX, unicode está activo por defecto, así que los marcadores en japonés salen normalmente correctos sin añadir nada. Para hacerlo explícito se escribe \usepackage[unicode]{hyperref} o \hypersetup{unicode}.

La vía tradicional pLaTeX / upLaTeX + dvipdfmx funciona de otro modo. La receta estándar es \usepackage[dvipdfmx]{hyperref} más el paquete pxjahyper. pxjahyper existe precisamente para producir marcadores japoneses sin texto ilegible bajo (u)pLaTeX, y viene con TeX Live. La opción emparentada es pdfencoding=auto, que decide sola: deja las cadenas tal cual mientras quepan en ASCII y cambia a Unicode cuando no (sobre todo para la familia pdfTeX; en motores Unicode, Unicode ya es el valor por defecto y la opción suele sobrar). En resumen: con LuaLaTeX no hay nada que hacer; con (u)pLaTeX se añade pxjahyper.

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

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

Comandos de referencia que añade hyperref: \autoref y \nameref

Junto con los enlaces, hyperref añade dos maneras de escribir una referencia. \autoref{key} sustituye a \ref y antepone automáticamente la palabra del tipo de destino —“section 3.4” para una sección, “Figure 3” para una figura— convirtiendo todo en enlace. Esa palabra se cambia redefiniendo \figureautorefname, \sectionautorefname y afines, que es también la vía de la localización. El otro, \nameref{key}, inserta no un número sino el texto del título mismo: referenciar la etiqueta de \section{Introduction} da “Introduction”, que es lo que se busca al citar por título y no por número. Si además hacen falta referencias múltiples y plurales automáticos, \cref de cleveref llega más lejos que \autoref; la comparación completa está en la página de referencias cruzadas.

Un \hypersetup que se puede copiar tal cual

Esta es la forma en la que acaban asentándose la mayoría de los documentos de trabajo. colorlinks=true quita los recuadros y colorea el texto, los colores van separados por tipo, bookmarksnumbered crea marcadores numerados y pdfusetitle mantiene los metadatos al paso de \title y \author. Para un documento pensado ante todo para imprenta, sustituya las cuatro líneas de colorlinks a urlcolor por la sola palabra hidelinks. Los enlaces se vuelven entonces invisibles en la página, mientras que quien lea el PDF podrá seguir pulsándolos.

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