LaTeX/Packages/Hyperref

From Wikibooks, the open-content textbooks collection

The package hyperref provides LaTeX the ability to create hyperlinks within the document, but it works only with pdflatex. If you load it, you will have the possibility to include interactive external links and all your internal references will be turned to hyperlinks. It does not work with the standard latex compiler because, at the beginning, LaTeX could create only DVI files that do not support hyperlinks. Then the compiler pdflatex was created and now it is possible to create PDF files directly from the LaTeX source, and PDF supports more features than DVI. In particular PDF supports hyperlinks, and the only way to introduce them in LaTeX is using hyperref. Moreover, PDF can contain other information about a document such as the title, the author, etc., and you can edit those using this same package.

[edit] Usage

The basic usage with the standard settings is straightforward. Just load the package in the preamble, at the end of all the other packages but prior to other settings:

\usepackage{hyperref}

This will automatically turn all your internal references into hyperlinks. It won't affect the way to write your documents: just keep on using the standard \label/\ref system; with hyperref those "connections" will become links and you will be able to click on them to be redirected to the right page. Moreover the table of contents, list of figures/tables and index will be made of hyperlinks, too.

The package provides three useful commands for inserting links pointing outside the document:

• \hyperref[label_name]{link text}: this will have the same effect as \ref{label_name} but will make the text link text a full link, instead. The two can be combined, for example in

we use \hyperref[mainlemma]{lemma \ref{mainlemma}}

If the lemma labelled as "mainlemma" was number 4.1.1, then the outputted text would be "we use lemma 4.1.1" with the hyperlink as expected.

• \url{my_url}: it will show the URL using a mono-spaced font and, if you click on it, your browser will be opened pointing at it.
• \href{my_url}{description}: it will show the string "description" using standard document font but, if you click on it, your browser will be opened pointing at "my_url". Here is an example:

\url{http://www.wikibooks.org}
\href{http://www.wikibooks.org}{wikibooks home}

both point at the same page, but in the first case the URL will be shown, while in the second case the URL will be hidden. Note that, if you print your document, the link stored using \href will not be shown anywhere in the document. You can use relative paths to link documents near the location of your current document; in order to do so, use the standard unix-like notation (./ is the current directory, ../ is the previous directory, etc.)

A possible way to insert emails is by

\href{mailto:my_address@wikibooks.org}{my_address@wikibooks.org}

it just shows your email address (so people can know it even if the document is printed on paper) but, if the reader clicks on it, (s)he can easily send you an email. Or, to incorporate the url package's formatting and line breaking abilities into the displayed text, use^[1]

\href{mailto:my_address@wikibooks.org}{\nolinkurl{my_address@wikibooks.org}}

When using this form, note that the \nolinkurl command is fragile and if the hyperlink is inside of a moving argument, it must be preceeded by a \protect command.

[edit] Customization

The standard settings should be fine for most users, but if you want to change something, you can easily do it. There are several variables you can change and there are two methods to pass those to the package. You can pass the options as an argument of the package when you load it (that's the standard way packages work), or you can use the \hypersetup package:

\hypersetup{option1, option2}

you can pass as many options as you want, separate them with a comma. Those options have to be in the form:

variable_name=new_value

exactly the same format has to be used if you pass those options to the package while loading it, like this:

\usepackage[pdftex,option1, option2]{hyperref}

Note that you always have to use the pdftex option, otherwise you will get an error; if you use the \hypersetup command, your code will be clearer and more readable (even if the effect is exactly the same).

Here is a list of the possible variables you can change (for the complete list, see the official documentation). The default values are written in an upright font:

In order to speed up your customization process, here is a list with the variables with their default value. Copy it in your document and make the changes you want. Next to the variables, there is a short explanations of their meaning:

\hypersetup{
    bookmarks=true,         % show bookmarks bar?
    unicode=false,          % non-Latin characters in Acrobat’s bookmarks
    pdftoolbar=true,        % show Acrobat’s toolbar?
    pdfmenubar=true,        % show Acrobat’s menu?
    pdffitwindow=true,      % page fit to window when opened
    pdftitle={My title},    % title
    pdfauthor={Author},     % author
    pdfsubject={Subject},   % subject of the document
    pdfnewwindow=true,      % links in new window
    pdfkeywords={keywords}, % list of keywords
    colorlinks=false,       % false: boxed links; true: colored links
    linkcolor=red,          % color of internal links
    citecolor=green,        % color of links to bibliography
    filecolor=magenta,      % color of file links
    urlcolor=cyan           % color of external links
}

If you don't need such a high customization, here are some smaller but useful examples. When creating PDFs destined for printing, colored links are not a good thing as they end up in gray in the final output, making it difficult to read. You can use color frames, which are not printed:

\usepackage{hyperref}
\hypersetup{colorlinks=false}

or make links black:

\usepackage[pdftex]{hyperref}
\hypersetup{
    colorlinks,%
    citecolor=black,%
    filecolor=black,%
    linkcolor=black,%
    urlcolor=black
}

When you just want to provide information for the Document Info section of the PDF file:

\usepackage[pdfauthor={Author's name},%
pdftitle={Document Title},%
pdftex]{hyperref}

By default, URLs are printed using mono-spaced fonts. If you don't like it and you want them to be printed with the same style of the rest of the text, you can use this:

 \urlstyle{rm}

[edit] Problems with Links

Messages like the following:

! pdfTeX warning (ext4): destination with the same
identifier (name{page.1}) has been already used,
duplicate ignored

appear when a counter gets reinitialized, for example by using the command \mainmatter provided by the book document class. It resets the page number counter to 1 prior to the first chapter of the book. But as the preface of the book also has a page number 1 all links to “page 1” would not be unique anymore, hence the notice that "duplicate has been ignored." The counter measure consists of putting plainpages=false into the hyperref options. This unfortunately only helps with the page counter. An even more radical solution is to use the option hypertexnames=false, but this will cause the page links in the index to stop working.

The best solution is to give each page a unique name by using the \pagenumbering command:

\pagenumbering{alph}    % a, b, c, ...
... titlepage, other front matter ...
\pagenumbering{roman}   % i, ii, iii, iv, ...
\setcounter{page}{1}
... table of contents, table of figures, ...
\pagenumbering{arabic}  % 1, 2, 3, 4, ...
\setcounter{page}{1}
... beginning of the main matter (chapter 1) ...

By changing the page numbering every time before the counter is reset, each page gets a unique name. In this case, the pages would be numbered a, b, c, i, ii, iii, iv, v, 1, 2, 3, 4, 5, ...

If you don't want the page numbers to be visible (for example, during the front matter part), use \pagestyle{empty} ... \pagestyle{plain}. The important point is that although the numbers are not visible, each page will have a unique name.

The problem can also occur with the algorithms package: because each algorithm uses the same line-numbering scheme, the line identifiers for the second and follow-on algorithms will be duplicates of the first.

[edit] Problems with Bookmarks

The text displayed by bookmarks does not always look like you expect it to look. Because bookmarks are "just text", much fewer characters are available for bookmarks than for normal LATEX text. Hyperref will normally notice such problems and put up a warning:

Package hyperref Warning:
Token not allowed in a PDFDocEncoded string:

You can now work around this problem by providing a text string for the bookmarks, which replaces the offending text:

\texorpdfstring{TEX text}{Bookmark Text}

Math expressions are a prime candidate for this kind of problem:

\section{\texorpdfstring{$E=mc^2$}{E=mc2}}

which turns \section{$E=mc^2$} to E=mc2 in the bookmark area. Color changes also do not travel well into bookmarks:

\section{\textcolor{red}{Red !}}

produces the string "redRed!". The command \textcolor gets ignored but its argument (red) gets printed. If you use:

\section{\texorpdfstring{\textcolor{red}{Red !}}{Red\ !}}

the result will be much more legible.

If you write your document in unicode and use the unicode option for the hyperref package you can use unicode characters in bookmarks. This will give you a much larger selection of characters to pick from when when using \texorpdfstring.

[edit] Problems with tables and figures

Since hyperref points to the caption created within the float environment, which is always set below a figure or table, the figure or table itself will not be visible^[2]. A workaround exists by using the package hypcap [1] with:

\usepackage[all]{hypcap}

Be sure to call this package after loading hyperref, which should otherwise be loaded last.

[edit] References

1. ↑ Email link with hyperref, url packages. comp.text.tex User Group. Retrieved on January 22, 2008.
2. ↑ http://www.ctan.org/tex-archive/macros/latex/contrib/hyperref/README