PDF 기본

개요

PDF 출력은 pdf 형식을 사용합니다. 예를 들어:

---
title: "My document"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

이 예시는 PDF 출력에 사용할 수 있는 몇 가지 옵션을 보여줍니다. 이 문서는 이러한 옵션과 다른 옵션을 자세히 설명합니다. 사용 가능한 전체 옵션 목록은 PDF 형식 참조를 참고하세요.

PDF 대신 원시 LaTeX 출력(.tex 파일)을 생성하려면 여기에서 문서화된 모든 옵션을 그대로 사용할 수 있습니다(자세한 내용은 아래 LaTeX 출력 섹션 참고).

Note

여기서는 LaTeX를 사용한 PDF 생성에만 집중하지만, Pandoc는 ConTeXt, roff ms 또는 HTML(wkhtmltopdf 사용)로 PDF를 생성하는 것도 지원합니다. 자세한 내용은 Pandoc의 PDF 만들기 문서를 참고하세요.

사전 준비

PDF를 만들려면 최신 TeX 배포판을 설치해야 합니다. TexLive 기반인 TinyTeX 사용을 권장하며, 다음 명령으로 설치할 수 있습니다:

Terminal
quarto install tinytex

다른 TeX 배포판과 PDF 컴파일 엔진 사용 방법은 PDF 엔진 문서를 참고하세요.

문서 클래스

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

PDF 문서에서는 다음 Pandoc 옵션이 기본값으로 설정됩니다:

format:
  pdf:
    documentclass: scrartcl
    papersize: letter

documentclass를 표준 article, report, book 클래스로 설정할 수도 있고, KOMA Script의 대응 클래스인 scrartcl, scrreprt, scrbook으로 설정할 수도 있으며, 설치된 LaTeX 패키지가 제공하는 다른 클래스도 사용할 수 있습니다.

Note

documentclass를 book 또는 scrbook으로 설정하면 PDF를 실제 책으로 인쇄/제본할 때 필요한 일반적인 요구 사항(예: 장이 홀수 페이지에서 시작, 여백 크기 교대 등)을 자동으로 처리합니다.

LaTeX 문서 옵션 사용자 지정에 대한 자세한 내용은 아래 출력 옵션 섹션을 참고하세요.

목차

toc 옵션을 사용하면 출력 문서에 자동 생성된 목차가 포함됩니다. toc-depth 옵션으로 목차에 포함할 섹션 수준을 지정할 수 있습니다. 기본값은 3이며(즉, 1, 2, 3단계 제목이 목차에 표시됩니다) 예시는 다음과 같습니다.

toc: true
toc-depth: 2

toc-title 옵션으로 목차 제목을 사용자 지정할 수 있습니다.

toc-title: Contents

목차에서 특정 제목을 제외하려면 .unnumbered와 .unlisted 클래스를 모두 추가합니다.

### More Options {.unnumbered .unlisted}

섹션 번호

number-sections 옵션을 사용하면 출력 문서의 섹션 제목에 번호가 붙습니다. 예:

number-sections: true

number-depth 옵션으로 번호를 붙일 가장 깊은 제목 수준을 지정할 수 있습니다(기본값은 모든 제목에 번호가 붙음). 예:

number-depth: 3

개별 제목에 번호를 붙이지 않으려면 .unnumbered 클래스를 추가합니다.

### More Options {.unnumbered}

문법 강조

Pandoc는 언어 이름이 지정된 fenced code blocks의 문법을 자동으로 강조합니다. 예:

```python
1 + 1
```

Pandoc는 140개 이상의 언어에 대해 문법 강조를 제공합니다(전체 목록은 quarto pandoc --list-highlight-languages 출력 참고). 지원되지 않는 언어의 강조 표시가 필요하다면 언어 이름으로 default를 사용하면 됩니다.

highlight-style로 지원되는 테마 중 하나를 지정해 코드 하이라이팅 스타일을 설정할 수 있습니다. 지원 테마: arrow, pygments, tango, espresso, zenburn, kate, monochrome, breezedark, haddock, atom-one, ayu, breeze, dracula, github, gruvbox, monokai, nord, oblivion, printing, radical, solarized, vim.

For example:

highlight-style: github

하이라이팅 테마는 단일 정의를 제공하거나, 밝은 배경용과 어두운 배경용 두 정의를 제공할 수 있습니다. 두 정의가 있을 때 Quarto는 코드 청크 배경의 밝기에 따라 적절한 스타일을 자동 선택합니다. 자동 선택을 피하려면 전체 이름(예: atom-one-dark)을 지정하면 됩니다.

기본적으로 코드는 접근성을 고려한 arrow 테마로 강조됩니다. arrow 라이트/다크 테마 예시는 다음과 같습니다.

Arrow 라이트 테마를 보여주는 코드 블록.

Arrow 다크 테마를 보여주는 코드 블록.

코드 주석

코드 블록과 실행 코드 셀의 코드 줄에 주석을 추가할 수 있습니다. 자세한 내용은 Code Annotation을 참고하세요.

출력 옵션

PDF 출력을 사용자 지정할 수 있는 다양한 옵션이 있습니다. 예:

  • 문서 클래스와 옵션 지정

  • 그림 및 표 목록 포함

  • geometry 및 hyperref 패키지 사용

  • 글꼴과 색상을 사용자 지정하는 여러 옵션

예를 들어 다음과 같이 몇 가지 옵션을 사용할 수 있습니다:

---
title: "My Document"
format: 
  pdf: 
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    mainfont: Times New Roman
    colorlinks: true
---

사용 가능한 모든 옵션은 Pandoc의 메타데이터 LaTeX 변수 문서를 참고하세요.

글꼴

기본 엔진인 lualatex 또는 xelatex 엔진을 사용하면 다음 YAML 옵션으로 글꼴을 지정할 수 있습니다:

옵션 문서 요소
sansfont 제목
mainfont 본문 텍스트
monofont 코드
mathfont 수식
CJKmainfont CJK 기본 글꼴 패밀리

이 옵션 값은 시스템에 설치된 글꼴의 패밀리 이름이어야 합니다. 예:

---
format: 
  pdf:
    mainfont: "Times New Roman"
---

글꼴은 fontspec 패키지로 설정됩니다. 해당 <fontoption>options 키로 추가 글꼴 기능을 설정할 수 있습니다. 예를 들어 제목 색상을 #39729E로 설정할 수 있습니다:

---
format: 
  pdf:
    sansfont: "Open Sans"
    sansfontoptions: 
      - Color=39729E
---

pdflatex

pdflatex 엔진을 사용하는 경우 LaTeX 글꼴 카탈로그에서 글꼴을 선택하여 fontfamily 옵션으로 지정하세요. 예:

---
title: pdflatex fonts
format:
  pdf:
    pdf-engine: pdflatex
    fontfamily: anttor
---

유니코드 문자

기본적으로 Quarto는 LaTeX에서 PDF를 생성할 때 lualatex 엔진을 사용합니다. lualatex는 유니코드 문자를 기본 지원하지만, 특정 유니코드 문자를 올바르게 조판하려면 일부 사용자 지정이 필요할 수 있습니다. 특히 문서에서 사용하는 문자를 지원하는 글꼴을 사용하는 것이 중요합니다. 특정 언어 문자를 지원하는 시스템 글꼴을 찾으려면 다음 명령을 사용할 수 있습니다:

Terminal
fc-list :lang=<lang> family

여기서 <lang>는 ISO 639 언어 코드입니다. 예를 들어 일본어 문자를 지원하는 글꼴 목록을 보려면 다음을 사용합니다:

Terminal
fc-list :lang=ja family

목록에서 글꼴 이름을 선택해 문서의 기본 글꼴로 사용하세요:

---
title: Unicode test
format: pdf
mainfont: "Hiragino Sans GB"
---

## Test Document

青黑體簡體中文,ヒラギノ角

유니코드 문자의 다른 일반적인 예로 그리스 문자를 포함한 문서가 있습니다:

greek.qmd
---
format: pdf
---

## α

```r
α <- 3
```

α is a great constant.
```

위와 같은 과정을 따라 그리스 문자를 지원하는 글꼴을 찾습니다:

Terminal
fc-list :lang=el family

그런 다음 적절한 글꼴 옵션을 설정하세요:

greek.qmd
---
format: 
  pdf:
    mainfont: "EB Garamond"
    sansfont: "Open Sans"
    monofont: "Roboto Mono"
---

(이 특정 글꼴들은 Google Fonts에서 사용할 수 있습니다.)

적절한 지원을 가진 글꼴을 사용하면 그리스 문자가 제목, 본문 텍스트, 코드 셀에서 올바르게 렌더링됩니다:

제목, 본문 텍스트, 코드 셀에 그리스 문자 알파가 표시된 PDF 스크린샷.

렌더링된 PDF의 그리스 문자

SVG 이미지

rsvg-convert로 PDF 변환

Quarto는 SVG 파일이 포함된 PDF 문서 렌더링을 지원하며, 렌더링 시 시스템 경로에 rsvg-convert가 있으면 이를 PDF 이미지로 자동 변환합니다.

rsvg-convert를 제공하는 librsvg 설치에 대한 자세한 내용은 https://wiki.gnome.org/Projects/LibRsvg를 참고하세요. 플랫폼별 설치 방법은 다음과 같습니다:

  • MacOS에서는 Homebrew 사용: brew install librsvg

  • Linux에서는 tarball 사용: https://download.gnome.org/sources/librsvg/

  • Windows에서는 chocolatey로 설치: choco install rsvg-convert 또는 Scoop 사용:

    # scoop bucket add r-bucket https://github.com/cderv/r-bucket.git
scoop install rsvg-convert

대안: Inkscape 사용

rsvg-convert 대신 Inkscape를 사용하려면 use-rsvg-convert: false를 설정해 기본 변환을 끌 수 있습니다. 그러면 SVG LaTeX 패키지를 사용해 \includesvg{}로 svg를 포함하며, Inkscape가 PDF로 변환합니다. 이를 위해 다음과 같은 설정이 필요합니다:

format:
  pdf:
    use-rsvg-convert: false
    pdf-engine-opts: ["-shell-escape"]

이 구성에는 다음이 필요합니다:

  • Inkscape 설치 및 시스템 PATH에서 사용 가능해야 함
  • 외부 프로그램 실행을 허용하기 위해 LaTeX 엔진에 -shell-escape 옵션 필요
  • SVG LaTeX 패키지(Quarto가 자동으로 포함)

플랫폼 고려사항

SVG 변환 도구의 가용성과 설치 용이성은 플랫폼마다 다릅니다:

  • Linux/macOS: rsvg-convert는 보통 패키지 관리자(librsvg 패키지)로 설치할 수 있습니다. 이 플랫폼에서는 이 방법을 권장합니다.
  • Windows: rsvg-convert 설치가 더 까다롭습니다. Scoop으로 설치할 수 있지만(위 참조), 대부분의 Windows 사용자는 SVG 대신 PNG 형식을 고려하는 것이 좋습니다.
  • Inkscape: 크로스 플랫폼으로 사용할 수 있지만 -shell-escape 설정이 필요합니다. Inkscape의 렌더링 기능이 꼭 필요할 때만 사용을 고려하세요.

다이어그램 형식에서는 호환성과 사용 편의성을 위해 일반적으로 PNG를 권장합니다. 자세한 내용은 아래 Note 1 을 참고하세요.

Note 1: 다이어그램용 SVG 형식

PDF 문서에서 Mermaid 또는 Graphviz 다이어그램을 사용할 때는 기본 PNG 형식을 권장합니다. mermaid-format: svg로 SVG 출력을 사용할 수 있지만 외부 도구가 필요합니다:

  • rsvg-convert(기본) - 위의 설치 지침 참고
  • Inkscape(대안) - use-rsvg-convert: false와 -shell-escape 설정 필요

SVG 형식은 다중 행 레이블을 가진 다이어그램에서 텍스트 잘림 같은 렌더링 문제가 있을 수 있습니다. 대부분의 사용자에게 PNG 형식이 더 나은 호환성과 사용 편의성을 제공합니다. 자세한 내용은 Diagrams를 참고하세요.

원격 이미지

URL로 원격 이미지를 직접 참조할 수 있습니다:

![Penguins](https://example.com/images/penguins.png)

이미지는 렌더링 중 자동으로 다운로드되어 PDF에 포함됩니다.

인용

PDF를 만들 때 citeproc 기반의 기본 Pandoc 인용 처리를 사용하거나, 대신 natbib 또는 BibLaTeX를 사용할 수 있습니다. 이는 cite-method 옵션으로 제어합니다. 예:

format:
  pdf: 
    cite-method: biblatex

기본값은 citeproc(Pandoc 내장 인용 프로세서)입니다.

인용 문법, 사용 가능한 참고문헌 형식 등에 대한 자세한 내용은 Quarto의 Citations 문서를 참고하세요.

옵션

natbib 또는 biblatex를 사용할 때 참고문헌 렌더링 방식에 영향을 주는 다음 추가 옵션을 지정할 수 있습니다:

옵션 설명
biblatexoptions biblatex 옵션 목록
natbiboptions natbib 옵션 목록
biblio-title 참고문헌 제목
biblio-style 참고문헌 스타일

Raw LaTeX

PDF 문서를 만들 때 Pandoc는 마크다운에 raw LaTeX 지시문을 섞어 사용할 수 있게 합니다. Pandoc는 Markdown에서 LaTeX를 이스케이프 없이 사용할 수 있게 하지만, 대신 raw 블록으로 감싸는 것을 권장합니다. 예:

```{=latex}
\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}
```

Raw LaTeX는 위와 같이 블록 요소로 지정하거나 `\textrm{hello}`{=latex}처럼 인라인 요소로 지정할 수 있습니다. Raw LaTeX 명령은 그대로 보존되어 LaTeX 작성기에 변경 없이 전달됩니다.

Warning

Raw LaTeX는 매우 편리하지만 HTML이나 MS Word 같은 다른 형식으로 렌더링할 때는 무시됩니다. 다른 형식으로 렌더링할 계획이라면 위 예시는 기본 마크다운 표를 사용해 작성하는 것이 더 좋습니다.

경우에 따라 raw LaTeX에 추가 LaTeX 패키지가 필요할 수 있습니다. 아래 LaTeX 포함 섹션에서 문서에 \usepackage 명령을 포함하는 방법을 설명합니다.

LaTeX 포함

다른 파일의 추가 콘텐츠를 문서에 포함하려면 include-in-* 옵션을 사용할 수 있습니다.

옵션 설명
include-in-header 헤더 끝에 file의 내용을 그대로 포함합니다. 예를 들어 HTML 문서에 특수 CSS/JavaScript를 포함하거나 LaTeX 프리앰블에 명령을 삽입하는 데 사용할 수 있습니다.
include-before-body 문서 본문 시작 부분에 file의 내용을 그대로 포함합니다(HTML에서는 <body> 태그 뒤, LaTeX에서는 \begin{document} 뒤). HTML 문서에 내비게이션 바나 배너를 넣는 데 사용할 수 있습니다.
include-after-body 문서 본문 끝에 file의 내용을 그대로 포함합니다(HTML에서는 </body> 태그 앞, LaTeX에서는 \end{document} 앞).

각 옵션에 대해 파일 하나 또는 여러 파일을 직접 지정하거나 file: 하위 키를 사용할 수 있습니다. YAML 헤더에 원시 콘텐츠를 포함하려면 text 하위 키를 사용하세요. text:를 사용할 때는 text: 뒤에 | 문자를 추가해 다중 줄 문자열임을 나타냅니다. file:이나 text:를 생략하면 Quarto는 파일을 제공하는 것으로 간주합니다.

예:

format:
  pdf:
    include-in-header:
      - text: |
          \usepackage{eplain}
          \usepackage{easy-todo}
      - file: packages.tex
      - macros.tex

include로 지정한 패키지가 로컬에 설치되어 있지 않다면 문서 렌더링 중 Quarto가 설치합니다.

LaTeX 출력

PDF 대신 LaTeX 파일(.tex)을 생성하려면(예: PDF를 직접 후처리하려는 경우) 두 가지 방법이 있습니다:

  1. pdf 형식 대신 latex 형식을 사용합니다. 예:

    format:
  latex:
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true

    위에서 문서화된 모든 PDF 형식 옵션은 latex 형식에서도 동일하게 작동합니다.

  2. pdf 형식과 함께 keep-tex 옵션을 사용합니다. 예:

    format:
  pdf:
    documentclass: report
    keep-tex: true

    이 방법은 미리보기용 PDF 파일을 생성하며, 함께 .tex 파일도 만들어 이후 처리를 할 수 있게 합니다.

두 방법 모두 .bbl 파일 등을 포함한 모든 LaTeX 임시 파일도 생성하며, 이는 LaTeX 소스를 요구하는 출판사에 필요할 수 있습니다.