책 출력 사용자 정의

이 문서는 책 프로젝트의 출력 사용자 정의 방법을 다룹니다. 지원되는 각 출력 포맷에서 책의 스타일과 모양을 조정하는 방법도 포함합니다.

포맷 옵션

렌더링 옵션(포맷별 옵션 포함)은 개별 마크다운 문서가 아니라 _quarto.yml 프로젝트 파일에 지정합니다. 책을 렌더링할 때 모든 챕터가 하나의 문서로 결합되며, 하나의 포맷 옵션 집합을 사용하기 때문입니다.

예시 설정은 다음과 같습니다.

highlight-style: pygments

format:
  html:
    theme: cosmo
    code-copy: true
  pdf: default
    
bibliography: references.bib
csl: citestyle.csl

위 설정에서 highlight-style 옵션은 모든 포맷에 적용되고, html 옵션은 HTML 출력에만 적용됩니다. 참고 문헌 관련 옵션도 자연스럽게 모든 포맷에 적용됩니다.

독자 도구

웹사이트 도구

HTML 책은 특수한 내비게이션 동작이 추가된 Quarto 웹사이트입니다. 따라서 웹사이트 개선을 위한 모든 기능을 책에서도 사용할 수 있습니다. 예:

웹사이트 도구를 사용할 때 중요한 점은, 이러한 도구를 웹사이트에서는 website 키 아래에 추가하지만 책에서는 동일한 옵션을 book 키 아래에 넣어야 한다는 것입니다. 예를 들어 웹사이트에서는 다음과 같이 파비콘과 트위터 카드를 추가합니다.

website:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

책에서는 book 키를 사용합니다.

book:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

사이드바 도구

책에는 자동으로 내비게이션 사이드바가 포함되며, 선택적으로 검색, 공유, 다운로드 등 다양한 도구를 추가할 수 있습니다. 다음은 이러한 옵션을 활성화하는 _quarto.yml 예시입니다.

book:
  title: "Hands-On Programming with R"
  author: "Garrett Grolemund"
  search: true
  repo-url: https://github.com/jjallaire/hopr/
  repo-actions: [edit]
  downloads: [pdf, epub]
  sharing: [twitter, facebook]
  
comments:
  hypothesis: true

이제 다음과 같은 도구가 표시됩니다.

바로 앞의 YAML 옵션으로 렌더링된 Quarto 페이지 스크린샷. 사이드바 상단에는 페이지의 GitHub 저장소로 이동하는 아이콘, PDF 다운로드 아이콘, 소셜 미디어 공유 아이콘이 있다. 바로 아래에는 검색창이 있다. 페이지 오른쪽 상단에는 Hypothesis 협업 주석 소프트웨어 아이콘이 있다. 오른쪽의 페이지 목차 아래에는 'Edit this Page' 링크가 있고, 그 왼쪽에는 GitHub 아이콘이 있다.

검색 상자는 책 전체에 대한 전체 텍스트 검색을 제공합니다.
사이드바에서 책 제목 바로 아래의 버튼은 GitHub 저장소 링크, PDF/EPUB 다운로드, Twitter/Facebook 공유 링크를 제공합니다.
오른쪽의 목차 아래에는 “Edit this page” 링크가 있으며, 현재 챕터의 GitHub 편집 화면으로 이동합니다. 이 예시에서는 repo-actions: [edit]를 지정했습니다. 선택적으로 issue와 source 동작도 추가할 수 있습니다(예: repo-actions: [edit, issue, source]). 저장소 링크를 사용자 정의하기 위한 추가 옵션(repo-subdir, repo-branch)도 있으니 저장소 링크 사용자 정의를 참고하세요.
오른쪽 가장자리에는 Hypothesis 댓글 바가 표시됩니다. 댓글은 모든 Quarto HTML 출력에서 사용할 수 있는 기능이므로 별도의 YAML 키로 제공됩니다.

사이드바 옵션

책은 Quarto 웹사이트의 표준 사이드바 컴포넌트를 사용합니다. 따라서 book 설정에서 사용 가능한 사이드바 옵션을 모두 사용할 수 있습니다. 예를 들어 다음과 같이 밝은 배경의 고정 사이드바를 지정할 수 있습니다.

book:
  title: "Hands-On Programming with R"
  author: "Garrett Grolemund"
  sidebar:
    style: docked
    background: light

표지 이미지

cover-image 옵션으로 EPUB 및/또는 HTML 포맷에 표지 이미지를 제공할 수 있습니다. 예:

book:
  cover-image: cover.png

포맷별로도 지정할 수 있습니다(예: EPUB에는 더 높은 해상도, HTML에는 더 낮은 해상도로 다운로드 시간을 줄이고 싶을 때). 예:

format:
   html: 
     cover-image: cover.png
   epub:
     cover-image: cover-highres.png

cover-image-alt 옵션으로 책 표지의 HTML 대체 텍스트를 지정할 수 있습니다.

book:
  cover-image: cover.png
  cover-image-alt: |
    책 표지를 설명하는 대체 텍스트

출력 경로

기본적으로 책 출력은 프로젝트의 _book 디렉터리에 작성됩니다. output-dir 프로젝트 옵션으로 변경할 수 있습니다. 예:

project:
  type: book
  output-dir: docs

PDF, EPUB 같은 단일 파일 출력물도 output-dir에 작성됩니다. 파일 이름은 책 title에서 파생됩니다. output-file 옵션으로 변경할 수 있습니다.

book:
  title: "My Book"
  output-file: "my-book"

output-file에는 파일 확장자를 포함하지 않아야 합니다(각 포맷에 맞는 확장자가 자동으로 추가됩니다).

LaTeX 출력

인쇄용 최종 원고를 만들기 전에 LaTeX 출력을 사용자 정의해야 하는 경우가 있습니다(예: 페이지 사이 텍스트 흐름이나 그림 주변 배치를 조정할 때). 이 경우 책을 완성한 뒤 latex 포맷으로 렌더링하는 것이 좋습니다.

Terminal

quarto render --to latex

책의 전체 LaTeX 소스는 _book/book-latex 디렉터리에 출력됩니다.

이 시점에서는 _book 디렉터리를 복사하거나 git 브랜치를 만들어 최종 LaTeX 수정을 진행하는 것이 좋습니다(LaTeX에서 수정한 내용은 마크다운 소스에 유지되지 않으며, 다음 렌더링 때 덮어쓰기 때문입니다).

HTML 스타일

HTML 출력은 커스텀 테마를 추가(또는 확장)하거나 일반 CSS 파일을 제공해 사용자 정의할 수 있습니다. theme 옵션으로 테마를 지정합니다.

format:
  html:
    theme: cosmo

테마를 더 사용자 정의하려면 커스텀 테마 파일을 추가합니다.

format:
  html:
    theme: [cosmo, theme.scss]

테마 파일을 만드는 방법은 HTML 테마 문서에서 확인할 수 있습니다.

또는 일반 CSS만 사용해도 됩니다. 예:

format:
  html:
    css: styles.css

EPUB 스타일

EPUB 출력도 CSS로 사용자 정의할 수 있습니다.

format:
  epub:
    css: epub-styles.css
    epub-cover-image: epub-cover.png

표지 이미지를 함께 지정한 것에 주목하세요. 다른 EPUB 옵션에 대해서는 Pandoc의 EPUB 문서를 참고하세요.

PDF 스타일

include-in-header 옵션으로 책의 프리앰블에 추가 LaTeX 지시문을 포함할 수 있습니다. documentclass 및 기타 옵션도 추가할 수 있습니다(자세한 내용은 Pandoc의 LaTeX 옵션 문서 참고). 예:

format:
  pdf: 
    documentclass: scrbook
    include-in-header: preamble.tex
    fontfamily: libertinus

Quarto는 PDF 책에 기본으로 KOMA Script scrreprt 문서 클래스를 사용합니다. KOMA-Script 클래스는 표준 클래스의 대체재로, 타이포그래피와 유연성에 중점을 둡니다.

위 예시처럼 KOMA scrbook으로 바꾸거나, 표준 LaTeX book, report 클래스를 사용할 수도 있습니다. book과 report의 차이점 요약은 https://tex.stackexchange.com/questions/36988에서 확인할 수 있습니다.

MS Word 스타일

MS Word 출력은 새 reference doc을 만든 뒤 책에 적용해 사용자 정의할 수 있습니다.

format:
  docx:
    reference-doc: custom-reference.docx

reference 문서를 만들고 사용자 정의하는 방법은 Word 템플릿 문서를 참고하세요.