하이퍼링크(hyperref)

대부분의 LaTeX 패키지는 자기 자리만 지킵니다. hyperref는 다릅니다. \ref와 \cite, 제목, 목차를 PDF 안에서 클릭할 수 있는 링크로 바꾸기 위해 LaTeX 자신의 명령을 상당수 안쪽에서 다시 정의하기 때문입니다. 이 한 가지 사실이 나머지 거의 전부를 설명합니다. 매뉴얼이 “가장 마지막에 불러오라”고 못 박는 이유도, cleveref만 그 뒤에 와야 하는 이유도, 그리고 많은 사람이 가장 먼저 꺼 버리는 링크를 둘러싼 빨간 테두리 의 존재 이유도 마찬가지입니다. 이 페이지에서는 링크의 모양, \href와 \url, PDF 메타데이터와 책갈피, 그리고 제목에 수식을 넣으면 반드시 마주치는 그 경고까지 다룹니다.

\usepackage{hyperref} 한 줄이 무엇을 링크로 만드는가

프리앰블에 \usepackage{hyperref} 라고 쓰기만 하면 됩니다. 아무 설정을 하지 않아도 문서 안의 모든 참조가 링크가 됩니다. \ref와 \pageref, \cite로 만든 문헌 인용, 목차와 그림·표 목록의 각 항목, 각주 기호, 색인 항목까지, 목적지를 특정할 수 있는 것은 모두 대상입니다. PDF 뷰어에서 클릭하면 해당 위치로 이동하고, URL은 브라우저에서 열립니다. 다만 링크로 만들고 싶지 않은 경우도 있습니다. 참조 명령에는 별표 형태 가 마련되어 있어, \ref*{key}, \pageref*{key}, \autoref*{key} 는 번호만 내고 링크는 걸지 않습니다.

hyperref를 왜 마지막에 불러오는가, 그리고 유일한 예외

hyperref는 프리앰블의 거의 마지막 에 둡니다. 이유는 앞머리에서 말한 대로, 이 패키지의 일이 LaTeX 명령을 대량으로 재정의하는 것이기 때문입니다. 같은 명령을 손대는 다른 패키지를 뒤에 불러오면 그 재정의가 덮여, 링크와 책갈피가 조용히 망가집니다. hyperref 매뉴얼도 이 조언을 분명히 적어 두었고, 거기에 각주를 달아 재정의 개수와 그에 따른 로드 순서 의존을 줄이는 작업이 시작되었다고 밝히고 있습니다. 즉 이것은 영구적인 법칙이 아니라 현시점의 우회책입니다. 패키지 로드 순서 자체는 문서 클래스와 프리앰블 페이지에서 다룹니다.

“마지막”의 예외는 사실상 하나, cleveref 입니다. cleveref는 hyperref가 정의한 것을 감지해 자기 참조 명령을 짜므로 순서가 뒤집히면 성립하지 않습니다. 이것은 조용히 깨지지 않습니다. TeX Live 2024에 들어 있는 cleveref.sty 는 \begin{document} 시점에 순서를 검사하고 ! Package cleveref Error: cleveref must be loaded after hyperref! 라고 말하며 멈춥니다. varioref까지 쓴다면 순서는 varioref → hyperref → cleveref 입니다. 매뉴얼이 명확히 금지하는 것이 하나 더 있습니다. hyperref를 \AtBeginDocument나 begindocument 훅 안에서 불러오면 안 됩니다. hyperref와 nameref 자신이 그 훅을 쓰기 때문에 실행 순서가 불안정해집니다. 불러오기를 늦춰야 한다면 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와 hidelinks — 아무도 원하지 않는 빨간 테두리 없애기

기본 상태의 hyperref는 링크를 색 있는 상자 로 둘러 표시합니다(colorlinks의 기본값은 false). 화면에서는 분명 눈에 잘 띄지만, 종이에 인쇄하면 곤란해집니다. 상자만 인쇄되고 링크 기능은 종이 위에 존재하지 않기 때문입니다. 독자에게는 쓸모를 알 수 없는 빨간 사각형이 본문에 흩어져 있을 뿐이고, 이것이 “hyperref를 넣었더니 모양이 망가졌다”는 감상의 정체입니다. 설정은 불러올 때 옵션으로 하거나, 나중에 \hypersetup{...} 에 key=value 를 쉼표로 나열해서 합니다. \hypersetup은 프리앰블 어디에 써도 됩니다.

실무에서 가장 먼저 넣는 것이 colorlinks=true 입니다. 테두리를 없애고 링크 글자 자체에 색 을 입히므로 인쇄해도 깔끔하고 화면에서도 읽기 좋습니다. 색은 종류별로 나뉘어 있고 기본값은 linkcolor 빨강, citecolor 초록, urlcolor 마젠타, filecolor 시안입니다. 이는 화면에서 구별하기 위한 배색이라 투고 논문에 그대로 쓰면 다소 요란합니다. 차분하게 만들려면 전부 같은 색으로 두는 allcolors 가 빠르고, 인쇄 중심이라면 답은 hidelinks 입니다. 색도 테두리도 넣지 않아 링크가 겉보기에는 완전히 사라지지만 클릭 기능은 남습니다. 이 조합이 가장 흔한 경우, 곧 PDF로 배포하면서 종이로도 읽는 문서에 잘 맞습니다.

\href와 \url — 바깥 세상으로 가는 링크

외부 URL 링크는 두 명령으로 만듭니다. \href{URL}{display text} 는 원하는 말에 링크를 걸고, \url{URL} 은 URL 자체를 고정폭으로 조판하면서 동시에 링크로 만듭니다. 주소를 본문에 보이고 싶으면 \url, 다른 말 뒤에 숨기고 싶으면 \href입니다. 이 둘의 값어치는 인수를 다루는 방식에 있습니다. URL에 흔한 LaTeX 특수 문자, 곧 %, #, ~, _ 를 URL 부분에서는 이스케이프 없이 그대로 쓸 수 있습니다(\url의 인수 안에는 몇 가지 제약이 남습니다). 고정폭 모양만 필요하고 링크는 필요 없다면 \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 과 \texorpdfstring

제목에 수식을 넣는 순간 hyperref는 거의 틀림없이 이 경고를 냅니다. 원인은 제목 문자열이 두 곳으로 간다 는 데 있습니다. 하나는 조판된 본문의 제목이고, 다른 하나는 PDF 책갈피에 들어가는 단순한 문자열 입니다. 책갈피는 PDF 규격상 그저 텍스트이므로 $ 나 ^, \emph 같은 명령이 들어갈 수 없습니다. hyperref는 쓸 수 없는 토큰을 하나씩 버리고, 버릴 때마다 무엇을 버렸는지 알립니다. 제목 자체는 여전히 제대로 조판되고 책갈피만 내용을 잃습니다. 경고를 무시하면 바로 그런 조용한 열화가 남습니다.

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.

해법은 \texorpdfstring{TeX용}{PDF 문자열용} 입니다. 첫 번째 인수는 조판에, 두 번째 인수는 책갈피에 쓰이므로 제목에는 수식을, 책갈피에는 풀어 쓴 형태를 줄 수 있습니다. \section{The value of \texorpdfstring{$x^2$}{x squared}} 처럼 씁니다. 한 가지 주의할 점이 있습니다. 두 번째 인수도 그대로 PDF 문자열이 되므로 거기에 x^2 라고 쓰면 이번에는 ^ 에 대해 같은 경고가 납니다. 두 번째 인수에는 기호를 남기지 말고 x squared 나 유니코드 x² 처럼 문자만 두십시오.

PDF 메타데이터 — pdftitle, pdfauthor, pdfusetitle

hyperref는 PDF의 문서 정보 도 기록합니다. 뷰어의 “문서 속성”에 나오는 항목으로, 문헌 관리 프로그램이 가져가고 여러 검색 색인이 읽는 것도 이것입니다. \hypersetup 에서 pdftitle(제목), pdfauthor(저자), pdfsubject(주제), pdfkeywords(키워드)로 지정합니다. 값에 쉼표나 등호가 들어가면 키 구분자와 충돌하므로 값을 중괄호로 감싸는 것 이 안전합니다. pdftitle={Foundations of Linear Algebra} 처럼 씁니다.

놓치기 쉬운 점은 이 항목들이 문서 자체의 \title, \author 와 별개 라는 것입니다. \title을 써도 메타데이터에는 아무것도 들어가지 않고, 메타데이터를 고쳐도 표지는 바뀌지 않습니다. 둘을 맞추려면 hyperref의 pdfusetitle 을 씁니다. 이 옵션은 \title과 \author 로부터 pdftitle과 pdfauthor 를 이끌어 내어 이중 관리를 없앱니다. 다만 반드시 패키지 옵션으로 넘겨야 합니다. 곧 \usepackage[pdfusetitle]{hyperref} 라고 씁니다. \hypersetup{pdfusetitle} 로 쓰면 판정 시점을 이미 지난 뒤라 경고도 없이 아무 일도 일어나지 않습니다. 제목 자체에 수식이나 \\ 가 들어 있다면 앞 절의 \texorpdfstring 이 필요합니다.

책갈피 — 제목에서 자동으로 만들어지는 PDF 아웃라인

책갈피(PDF 아웃라인)는 뷰어가 페이지 옆에 보여 주는 접을 수 있는 제목 목록입니다. 100쪽이 넘는 문서에서는 목차보다 이쪽을 훨씬 자주 씁니다. hyperref는 문서의 장·절 같은 제목에서 자동으로 책갈피를 생성 합니다(bookmarks=true가 기본값). 절 번호까지 넣고 싶으면 bookmarksnumbered=true, 처음부터 트리를 펼쳐 두고 싶으면 bookmarksopen=true 를 지정합니다. 책갈피는 .out 이라는 보조 파일을 거치므로 목차와 마찬가지로 자리 잡을 때까지 여러 번 컴파일 해야 합니다.

복잡한 문서에서 책갈피가 흐트러질 때, 곧 순서가 바뀌거나 계층이 깨지거나 항목이 사라질 때의 표준 해법은 hyperref 뒤 에 불러오는 bookmark 패키지입니다. hyperref의 오래된 책갈피 코드를 대체하고 .out 처리를 안정화하며, 더해서 책갈피 항목의 굵기와 색 까지 설정할 수 있게 합니다. 세부 조정은 \bookmarksetup{...} 으로 합니다. 비용이 사실상 없으므로 긴 문서라면 처음부터 넣어 두어도 좋습니다.

일본어 등 비 ASCII 책갈피가 깨질 때

책갈피와 메타데이터는 PDF 안에 문자열로 기록되므로, 거기에 일본어나 중국어, 키릴 문자처럼 ASCII를 넘는 글자가 들어가면 인코딩 문제가 드러납니다. 핵심은 Unicode로 내보내는 것 입니다. LuaLaTeX과 XeLaTeX 에서는 unicode 가 기본으로 켜져 있어, 보통은 아무것도 더하지 않아도 일본어 책갈피가 제대로 나옵니다. 명시하려면 \usepackage[unicode]{hyperref} 또는 \hypersetup{unicode} 를 씁니다.

전통적인 pLaTeX / upLaTeX + dvipdfmx 경로는 사정이 다릅니다. 표준 방법은 \usepackage[dvipdfmx]{hyperref} 에 pxjahyper 패키지를 더하는 것입니다. pxjahyper 는 (u)pLaTeX에서 일본어 책갈피를 깨짐 없이 만들기 위해 존재하며 TeX Live에 함께 들어 있습니다. 관련 옵션은 pdfencoding=auto 로, 문자열이 ASCII에 들어가면 그대로 두고 아니면 Unicode로 전환하는 자동 판정입니다(주로 pdfTeX 계열용. Unicode 엔진에서는 이미 기본이 Unicode라 보통 필요 없습니다). 요컨대 LuaLaTeX이면 아무것도 하지 않고, (u)pLaTeX이면 pxjahyper 를 기억하면 충분합니다.

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

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

hyperref가 더해 주는 참조 명령 — \autoref와 \nameref

링크를 만드는 김에 hyperref는 참조를 쓰는 방법도 두 가지 더합니다. \autoref{key} 는 \ref 대신 쓰며, 참조 대상의 종류에 따라 말을 자동으로 앞에 붙이고 전체를 링크로 만듭니다. 절이면 “section 3.4”, 그림이면 “Figure 3”입니다. 앞에 붙는 말은 \figureautorefname, \sectionautorefname 등을 재정의해 바꾸며, 현지화도 같은 절차입니다. 다른 하나인 \nameref{key} 는 번호가 아니라 제목 문자열 자체 를 넣습니다. \section{Introduction} 의 이름표를 참조하면 “Introduction”이 나오므로, 번호가 아니라 제목으로 인용하고 싶을 때 씁니다. 여러 참조와 단복수 자동 처리까지 필요하다면 cleveref 의 \cref 가 \autoref 보다 멀리 갑니다. 전체 비교는 상호 참조 페이지에 있습니다.

그대로 가져다 쓸 수 있는 \hypersetup 설정

실무 문서가 대개 자리 잡는 형태는 다음과 같습니다. colorlinks=true 로 테두리를 없애고 글자에 색을 입히고, 색은 종류별로 나누고, bookmarksnumbered 로 번호가 붙은 책갈피를 만들고, pdfusetitle 로 메타데이터를 \title, \author 와 맞춥니다. 인쇄 중심 문서라면 colorlinks 부터 urlcolor 까지 네 줄을 hidelinks 한 단어로 바꾸십시오. 그러면 링크는 지면에서 보이지 않게 되지만 PDF로 읽는 사람에게는 클릭 기능이 그대로 남습니다.

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