책 상호 참조

개요

웹사이트와 책의 중요한 차이 중 하나는, 책이 웹 출력 외에도 하나의 연속 문서(예: PDF 또는 MS Word 문서)로 렌더링될 수 있다는 점입니다. 또한 책은 디지털로 읽히기도 하고 그렇지 않을 수도 있으므로, 내부 하이퍼링크가 항상 사용 가능한 것은 아닙니다.

이러한 모든 매체에서 책을 소비할 수 있도록, 책의 다른 챕터나 챕터 내 섹션으로 연결되는 링크를 만들 때는 특별한 주의가 필요합니다(HTML 출력만 대상으로 하는 책이라면 일반 하이퍼링크를 자유롭게 사용해도 됩니다).

Quarto 상호 참조는 그림, 표, 수식, 섹션, 목록, 정리, 증명에 대해 자동 번호와 참조를 제공합니다. 책에서는 상호 참조가 챕터 간에도 동작한다는 점만 다르고, 나머지는 동일합니다.

상호 참조 사용이 익숙하지 않다면, 먼저 상호 참조 문서를 읽어 보세요.

그림, 표 또는 다른 상호 참조 대상에 대한 참조를 만들려면 @ 구문(인용과 유사)을 사용하고 참조 대상의 ID/레이블을 지정합니다. 예:

섬별 분포는 @fig-penguins-by-island 를 참고하세요.

이 방식으로 만든 참조는 챕터 간에도 자동으로 해석됩니다(참조에는 필요한 챕터 번호가 포함됩니다).

챕터나 섹션을 참조 가능하게 만들려면 주 제목에 #sec 접두사를 추가합니다. 예:

# Introduction {#sec-introduction}

레이블 접두사

챕터를 상호 참조 가능하게 하려면 레이블이 반드시 sec- 접두사로 시작해야 합니다.

섹션을 참조하려면, 위의 그림 예시처럼 @ 식별자를 사용해 상호 참조를 추가합니다.

자세한 논의는 @sec-introduction 을 참고하세요.

예를 들어 다음과 같이 렌더링됩니다.

자세한 논의는 1장을 참고하세요.

적절한 접두사(“챕터” 또는 “섹션”)는 제목의 수준에 따라 자동으로 추가됩니다. 접두사를 숨기려면 대괄호 문법을 사용하고 @ 앞에 -를 붙입니다. 예: [-@sec-introduction]는 “챕터” 접두사 없이 “1”만 출력합니다.

사용자 정의 접두사를 제공하려면 대괄호 문법에서 접두사를 직접 작성합니다. 예:

모델 진단 시각화에 대한 자세한 내용은 [챕터 @sec-visualization]을 참고하세요.

예를 들어 다음과 같이 렌더링될 수 있습니다.

모델 진단 시각화에 대한 자세한 내용은 챕터 1.2을 참고하세요.

기본적으로 문서의 모든 제목은 번호가 붙은 섹션을 생성합니다. number-depth 옵션으로 번호 깊이를 사용자 정의할 수 있습니다. 예를 들어 챕터 바로 아래 수준만 번호를 매기려면 다음을 사용합니다.

number-depth: 2

toc-depth는 number-depth와 독립적입니다(즉, number-depth로 번호가 가려지면 TOC에는 번호 없는 항목이 포함될 수 있습니다).

책에서는 그림, 표 등 상호 참조 대상에 챕터 번호가 자동으로 포함됩니다. 예를 들어 책의 3장에서 다음 마크다운을 사용했다면:

@fig-geo-comparison 에서 볼 수 있듯이, 서부 지역은 산불 발생 빈도가 훨씬 높습니다.

다음과 같이 렌더링될 수 있습니다.

그림 3.2에서 볼 수 있듯이, 서부 지역은 산불 발생 빈도가 훨씬 높습니다.

책은 번호 없는 챕터도 지원하지만, 번호가 없는 챕터 안의 콘텐츠에는 상호 참조를 만들 수 없습니다.

HTML 전용 책(또는 인쇄될 것으로 예상하지 않는 PDF/MS Word 책)을 만드는 경우에는 섹션 상호 참조 대신 일반 하이퍼링크를 사용해도 괜찮습니다.

책 안에서 하이퍼링크를 만들려면 소스 파일을 링크 대상으로 지정하세요. 특정 섹션으로 연결하려면 소스 파일에 해시 식별자(#)를 추가할 수 있습니다. 예:

[about](about.qmd)
[about](about.qmd#section)

소스 파일을 링크 대상으로 사용하면 HTML 출력과 단일 파일 출력(PDF/MS Word 등) 모두에서 링크가 올바르게 해석됩니다.

인쇄 출력이 대상이라면 위와 같은 단순 링크 대신 챕터/섹션에 대한 명시적 상호 참조를 사용하는 것이 좋습니다. 인쇄물에서는 링크가 탐색 불가능하므로, 하이퍼링크 대신 “sec. 5.3” 같은 번호 참조를 제공해야 합니다.