책 구조

개요

Quarto 책의 구조는 챕터 목록처럼 단순할 수도 있고, 여러 파트 및/또는 부록을 포함하도록 구성할 수도 있습니다. Quarto 책의 챕터와 섹션은 자동으로 번호가 매겨지며(상호 참조용), 책의 일부는 번호 없이 유지하도록 지정할 수도 있습니다.

quarto create project book이 생성하는 간단한 책 설정은 기본을 보여 줍니다. 책 속성(제목, 저자, 챕터 구조 등)은 book 아래에 나열됩니다.

_quarto.yml
book:
  title: "mybook"
  author: "Jane Doe"
  date: "5/9/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd
  • index.qmd 파일은 필수입니다(Quarto 책은 HTML 포맷의 웹사이트도 만들기 때문입니다). 이 페이지에는 서문, 감사의 글 등을 포함해야 합니다. 책의 HTML 버전은 index.qmd를 홈 페이지로 사용하고, cover-image가 제공되면 해당 페이지에 표시합니다.
  • chapters의 나머지는 하나 이상의 챕터를 포함합니다.
  • references.qmd 파일에는 생성된 참고 문헌 목록이 포함됩니다(자세한 내용은 참고 문헌을 참고).

모든 챕터와 모든 포맷에 적용할 렌더링 옵션은 _quarto.yml의 최상위에 둡니다(book 아래가 아님).

_quarto.yml
bibliography: references.bib

특정 포맷에만 적용할 옵션은 format 아래에 둡니다.

_quarto.yml
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

제목

렌더링 옵션은 _quarto.yml에 제공되므로, 챕터 상단에는 보통 1단계 제목만 표시됩니다. 예:

intro.qmd
# Introduction

다음과 같이 YAML front matter에 제목을 지정하는 것도 여전히 유효합니다.

intro.qmd
---
title: "Introduction"
---

1단계 제목이나 YAML front matter의 제목이 없으면, 페이지의 첫 번째 제목이 제목으로 사용됩니다.

챕터 번호

모든 챕터는 기본적으로 번호가 매겨집니다. 챕터에 번호를 매기지 않으려면 해당 챕터의 주 제목에 .unnumbered 클래스를 추가하세요. 예를 들어 index.qmd의 챕터 번호를 생략하는 경우가 일반적입니다.

index.qmd
# Preface {.unnumbered}

번호가 있는 챕터와 없는 챕터를 섞어 사용할 수 있습니다. 다만 번호가 없는 챕터 안의 그림, 표 등에는 상호 참조를 만들 수 없습니다. 따라서 번호 없는 챕터는 서문 콘텐츠나 책 끝의 참고 문헌 등에 주로 사용합니다.

섹션 번호

number-depth 옵션으로 번호 깊이를 지정할 수 있습니다. 예를 들어 챕터 바로 아래 수준만 번호를 매기려면 다음을 사용합니다.

_quarto.yml
number-depth: 1

number-depth는 book 옵션이 아니라 포맷 옵션이므로, _quarto.yml의 최상위에 둡니다( book 아래가 아님). 특정 포맷에만 number-depth를 적용하려면 format 아래에 두세요.

_quarto.yml
format:
  pdf:
    number-depth: 1

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

참고 문헌

책에서 참고 문헌을 생성하고 싶은 위치에 #refs ID를 가진 div를 포함하세요. 예를 들어 quarto create project book이 생성한 references.qmd 파일에는 다음이 들어 있습니다.

references.qmd
# References {.unnumbered}

::: {#refs}
:::

챕터 제목은 원하는 대로 변경할 수 있고, .unnumbered를 제거해 다른 챕터처럼 번호를 붙일 수도 있으며, 필요하다면 참고 문헌 앞뒤에 다른 콘텐츠를 추가할 수 있습니다.

인덱스 만들기

PDF 출력의 경우 LaTeX makeidx 패키지와 \index 명령으로 인덱스를 만들 수 있습니다.

책의 PDF 출력에 인덱스를 추가하려면 _quarto.yml의 pdf 포맷 설정에 다음 include-in-header와 include-after-body 항목을 추가합니다.

_quarto.yml
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{makeidx}
        \makeindex
    include-after-body: 
      text: |
        \printindex

그 다음 원하는 위치에 \index{entry} 명령을 추가합니다. 예:

chapter.qmd
Markdown\index{Markdown} allows you to write using
an easy-to-read, easy-to-write plain text format.

또는 imakeidx 패키지를 사용할 수도 있습니다. 이 패키지는 인덱스 형식을 위한 추가 기능을 제공합니다. 예:

_quarto.yml
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{imakeidx}
        \makeindex[intoc=true, columns=3, columnseprule=true, options=-s latex/indexstyles.ist]
    include-after-body: 
      text: |
        \printindex

위 예시에서 intoc=true는 목차에 인덱스 항목을 포함하고, columns=3은 인덱스를 3열로 구성하며, columnseprule=true는 열 사이에 선을 표시합니다. 마지막으로 options=-s latex/indexstyles.ist는 latex/indexstyles.ist에 있는 인덱스 스타일 파일의 추가 옵션을 사용합니다. imakeidx 패키지에는 더 많은 기능이 있으니 자세한 내용은 해당 문서를 참고하세요.

\index 명령은 PDF가 아닌 출력에서는 자동으로 무시됩니다.

파트와 부록

Note참고

EPUB 및 Word(Docx) 포맷은 현재 책을 파트로 구성하는 기능을 지원하지 않습니다. 이 포맷으로 파트를 포함한 책을 렌더링하면 파트는 무시됩니다.

chapters 안에 part를 사용해 책을 파트로 나눌 수 있습니다. 예:

_quarto.yml
book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: dice.qmd
      chapters: 
        - basics.qmd
        - packages.qmd
    - part: cards.qmd
      chapters:
        - objects.qmd
        - notation.qmd
        - modifying.qmd
        - environments.qmd

dice.qmd와 cards.qmd 마크다운 파일에는 파트 제목(1단계 제목)과 파트에 대한 소개 콘텐츠가 포함됩니다. 파트 제목만 필요하다면 다음과 같은 문법을 사용할 수도 있습니다.

_quarto.yml
book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "Dice"
      chapters: 
        - basics.qmd
        - packages.qmd

book 설정에 appendices 키를 추가하면 부록을 포함할 수 있습니다. 예:

_quarto.yml
book:
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd
  appendices:
    - tools.qmd
    - resources.qmd

파트와 부록은 HTML 출력에서 다음과 같이 표시됩니다.

Quarto로 렌더링된 책의 시작 페이지 스크린샷. 사이드바에는 굵은 섹션 제목이 세 개로 구분되어 있으며, 위에서부터 'PROJECT 1: WEIGHTED DICE', 'PROJECT 2: PLAYING CARDS', 'APPENDICES.'

LaTeX 출력에서는 파트에 \part 명령이 사용됩니다. EPUB 및 MS Word 출력에서는 파트가 완전히 무시됩니다.

부록은 대문자 알파벳으로 번호가 매겨지며, 제목에는 부록임을 나타내는 접두사가 삽입됩니다(예: “Appendix A — Additional Resources”). 다음 옵션으로 접두사와 구분자를 사용자 정의할 수 있습니다.

_quarto.yml
crossref:
  appendix-title: "App."
  appendix-delim: ":"

위 설정을 적용하면 예시는 “App. A: Additional Resources”로 출력됩니다. crossref는 포맷 옵션이며 book 아래에 중첩되지 않습니다.

페이지 네비게이션

여러 페이지가 섹션/하위 섹션에 있는 book라면, 방금 읽은 페이지의 하단에서 다음(또는 이전) 페이지로 이동할 수 있게 하는 것이 편리합니다. 다음 설정으로 활성화할 수 있습니다:

_quarto.yml
book:
  page-navigation: true

활성화되면 다음 또는 이전 페이지가 있을 때(다음/이전 섹션 포함) 페이지 하단에 네비게이션이 표시됩니다. 이 옵션은 책에서는 기본 활성화지만 웹사이트에서는 기본 비활성화입니다.

페이지 수준에서 YAML 헤더에 page-navigation을 지정해 네비게이션을 활성화/비활성화할 수도 있습니다. 예:

basics.qmd
---
page-navigation: false
---

디렉터리 내 모든 페이지의 네비게이션을 제어하려면 _metadata.yml에 page-navigation을 지정합니다:

_metadata.yml
page-navigation: false

페이지 푸터

page-footer 옵션을 사용하면 book의 모든 페이지에 공통 푸터를 제공할 수 있습니다. 가장 단순한 푸터는 가운데 정렬되어 더 연한 서체로 표시되는 텍스트를 제공합니다:

_quarto.yml
book:
  page-footer: "Copyright 2021, Norah Jones"

또는 푸터의 left, right, center 영역을 개별적으로 지정할 수 있습니다:

_quarto.yml
book:
  page-footer: 
    left: "Copyright 2021, Norah Jones" 
    right: 
      - icon: github
        href: https://github.com/
      - icon: twitter 
        href: https://twitter.com/

위 예시에서 right 영역에는 텍스트 대신 GitHub와 Twitter로 이동하는 탐색 항목을 포함했습니다. 푸터의 어떤 영역에도 탐색 항목을 포함할 수 있습니다.

background, foreground, border 옵션으로 푸터의 모양을 더 세밀하게 제어할 수 있습니다. 기본적으로 푸터에는 배경색이 없고 상단 테두리가 있습니다. 테두리를 제거하려면 다음과 같이 설정합니다:

_quarto.yml
book:
  page-footer:
    border: false

밝은 배경(예: 내비게이션 바와 맞추기)을 사용하려면 다음과 같이 설정합니다:

_quarto.yml
book:
  page-footer:
    background: light

명시하지 않는 한, 푸터에 표시되는 요소의 색상(foreground)은 푸터 배경과 대비되는 색으로 자동 결정됩니다.