튜토리얼: 저작

도구 선택

R 또는 Python?

이 튜토리얼은 R 또는 Python 코드 예제를 사용해 따라갈 수 있습니다. 선호하는 언어를 선택하세요.

R 예제를 보도록 선택했습니다. 안내서 전반에서 언제든지 Python으로 전환할 수 있습니다.

Python 예제를 보도록 선택했습니다. 안내서 전반에서 언제든지 R로 전환할 수 있습니다.

개요

이 튜토리얼에서는 Quarto의 작성 기능을 더 살펴봅니다. 여러 형식으로 문서를 렌더링하는 방법과 목차, 수식, 인용, 상호 참조 등 구성 요소를 추가하는 방법을 다룹니다.

다른 작성 방식

이 튜토리얼은 .qmd 문서의 소스를 편집하는 방식에 초점을 둡니다. Positron은 두 가지 다른 작성 방법도 지원합니다.

비주얼 에디터는 WYSIWYG 인터페이스로 .qmd 문서를 만들고 편집할 수 있습니다. 마크다운을 직접 작성하지 않고 문서를 만들고 싶은 사용자에게 유용합니다.
노트북 에디터는 .ipynb 노트북을 편집하기 위한 것입니다. Jupyter 노트북에 익숙하면서 Quarto 기능을 활용하고 싶은 사용자에게 적합합니다.

출력 형식

Quarto는 수십 가지 출력 형식으로 노트북을 렌더링할 수 있습니다. 기본값은 html 형식이며, 문서 옵션에서 다른 형식(또는 여러 형식)을 지정할 수 있습니다.

형식 옵션

authoring.qmd라는 새 파일을 만들고, 여러 형식으로 렌더링되도록 정의한 다음 각 형식에 옵션을 추가해 봅시다. 새 Quarto 문서를 만들려면 Quarto: New Document 명령을 실행하거나 File > New File … 메뉴에서 Quarto Document를 선택하세요.

파일을 authoring.qmd로 저장한 뒤 YAML 헤더를 다음과 같이 편집하세요.

---
title: "Quarto Document"
author: "Norah Jones"
format: pdf
---

기본 출력 형식으로 pdf를 지정했습니다(format 옵션을 제외하면 기본값은 html입니다).

이제 PDF 출력 제어를 위한 몇 가지 옵션을 추가해 봅시다.

---
title: "Quarto Document"
author: "Norah Jones"
format: 
  pdf: 
    toc: true
    number-sections: true
---

format: pdf에 LaTeX 필요

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

Terminal

quarto install tinytex

여러 형식

작성하는 문서가 하나의 출력 형식만 갖는 경우도 있지만, 많은 경우 여러 형식을 지원하고 싶을 것입니다. 문서에 html과 docx 형식을 추가해 봅시다.

---
title: "Quarto Document"
author: "Norah Jones"
toc: true
number-sections: true
highlight-style: pygments
format: 
  pdf: 
    geometry: 
      - top=30mm
      - left=20mm
  html: 
    code-fold: true
    html-math-method: katex
  docx: default
---

여기에는 많은 내용이 있습니다. 조금 나누어 보겠습니다. 첫 두 줄은 출력 형식과는 무관한 일반 문서 메타데이터입니다.

title: "Quarto Document"
author: "Norah Jones"

다음 세 줄은 모든 형식에 적용되는 문서 형식 옵션이므로 루트 수준에 지정됩니다.

toc: true
number-sections: true
highlight-style: pygments

다음은 format 옵션이며, 형식별 옵션을 제공합니다.

format:
  pdf:
    geometry: 
      - top=30mm
      - left=20mm
  html: 
    code-fold: true
    html-math-method: katex
  docx: default

pdf와 html 형식에 각각 한두 개의 옵션이 지정되어 있습니다. 예를 들어 HTML 출력에서는 사용자가 코드 표시 여부를 제어할 수 있도록 code-fold: true를 지정하고, 수학 텍스트는 katex로 렌더링합니다. PDF의 경우 여백을 정의합니다. docx 형식은 조금 다른데, docx: default라고 지정되어 있습니다. 이는 해당 형식의 기본 옵션을 그대로 사용한다는 의미입니다.

렌더링

Quarto: Preview 명령, 도구 모음의 미리보기 버튼, 또는 단축키 로 문서를 미리보기하면, 문서 헤더에 지정된 첫 번째 형식이 렌더링되어 미리보기 됩니다. 이 경우 authoring.pdf 파일이 생성되어 Viewer 패널에서 열립니다.

특정 형식을 미리보려면 Quarto: Preview Format… 명령을 실행하고 다른 형식을 선택하세요. 선택한 형식은 이후 미리보기에서 계속 사용됩니다. 기본 형식이나 다른 형식으로 돌아가려면 Quarto: Preview Format…을 다시 실행하세요.

문서 헤더에 지정된 모든 형식을 렌더링하려면 Quarto: Render Document 명령을 실행하세요. 그러면 다음 파일이 생성됩니다.

authoring.pdf
authoring.html
authoring.docx

섹션

목차와/또는 섹션 번호를 사용하면 독자가 문서를 더 쉽게 탐색할 수 있습니다. 문서 옵션에 toc 및/또는 number-sections를 추가하면 됩니다. 이 옵션들은 보통 모든 형식에 공통으로 적용되므로 루트 수준에 지정합니다.

---
title: Quarto Basics
author: Norah Jones
date: 'May 22, 2021'
toc: true
number-sections: true
---

## Colors

- Red
- Green 
- Blue

## Shapes

- Square
- Circle
- Triangle

## Textures

- Smooth
- Bumpy
- Fuzzy

이 문서를 HTML로 렌더링하면 다음과 같습니다.

목차와 섹션 번호의 동작을 제어하는 다양한 옵션이 있습니다. 자세한 내용은 출력 형식 문서(예: HTML, PDF, MS Word)를 참고하세요.

수식

마크다운에서 LaTeX 수식을 사용할 수 있습니다.

Einstein's theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$

렌더링하면 다음과 같습니다.

Einstein’s theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$

인라인 수식은 $…$ 로 감싸며, 새 줄(display) 수식을 만들려면 $$…$$를 사용합니다. 자세한 내용은 마크다운 수식 문서를 참고하세요.

인용

Quarto 문서에서 다른 작업을 인용하려면 먼저 지원 형식(BibTeX 또는 CSL)의 참고문헌 파일을 만듭니다. 그런 다음 문서에 bibliography YAML 메타데이터 옵션으로 참고문헌을 연결합니다.

다음은 참고문헌과 단일 인용을 포함한 문서입니다.

---
title: Quarto Basics
format: html
bibliography: references.bib
---

## Overview

Knuth says always be literate [@knuth1984].

## References

references.bib 내용

references.bib

@article{knuth1984,
  title={Literate programming},
  author={Knuth, Donald E.},
  journal={The Computer Journal},
  volume={27},
  number={2},
  pages={97--111},
  year={1984},
  publisher={British Computer Society}
}

참고문헌 항목은 @citeid 문법으로 인용합니다.

 Knuth says always be literate [@knuth1984].

참고문헌은 문서 끝에 포함되므로 소스 파일 하단에 ## References 제목을 추가합니다.

렌더링 결과는 다음과 같습니다.

Rendered document with references section at the bottom the content of which reads 'Knuth, Donald E. 1984. Literate Programming. The Computer Journal 27 (2): 97-111.'

@ 인용 문법은 접두사, 접미사, 위치 지정자, 본문 내 인용을 포함해 매우 유연합니다. 자세한 내용은 인용 문서를 참고하세요.

상호 참조

상호 참조는 그림, 표, 수식, 섹션에 번호와 하이퍼링크를 제공해 문서 탐색을 쉽게 합니다. 상호 참조 가능한 항목에는 일반적으로 레이블(고유 식별자)과 캡션이 필요합니다.

다음 예시는 다양한 유형의 항목을 상호 참조하는 방법을 보여줍니다.

---
title: Quarto Crossrefs
format: html
---

## Overview

See @fig-simple in @sec-plot for a demonstration of a simple plot. 

See @eq-stddev to better understand standard deviation.

## Plot {#sec-plot}

```{r}
#| label: fig-simple
#| fig-cap: "Simple Plot"
plot(c(1, 23, 2, 4), type = "l", ann = FALSE)
```

## Equation {#sec-equation}

$$
s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
$$ {#eq-stddev}

---
title: Quarto Crossrefs
format: html
---

## Overview

See @fig-simple in @sec-plot for a demonstration of a simple plot. 

See @eq-stddev to better understand standard deviation.

## Plot {#sec-plot}

```{python}
#| label: fig-simple
#| fig-cap: "Simple Plot"
import matplotlib.pyplot as plt
plt.plot([1,23,2,4])
plt.show()
```

## Equation {#sec-equation}

$$
s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
$$ {#eq-stddev}

섹션, 그림, 수식을 상호 참조했습니다. 아래 표는 각 항목을 어떻게 표현하는지 보여줍니다.

Entity	Reference	Label / Caption
Section	`@sec-plot`	ID added to heading: `# Plot {#sec-plot}`
Figure	`@fig-simple`	YAML options in code cell: `#\| label: fig-simple #\| fig-cap: "Simple Plot"`
Equation	`@eq-stddev`	At end of display equation: `$$ {#eq-stddev}`

그리고 마지막으로 이 문서를 렌더링한 결과는 다음과 같습니다.

Rendered page with linked cross-references to figures and equations.

자세한 내용은 상호 참조 문서를 참고하세요. 캡션과 참조 텍스트(예: “Figure” 대신 “Fig.” 사용)를 커스터마이즈하는 방법도 포함되어 있습니다.

Callout

Callout은 특정 개념에 추가 주의를 끌거나, 특정 콘텐츠가 보조 정보이거나 일부 시나리오에만 적용됨을 더 명확하게 나타내는 데 유용합니다.

Callout은 특수 callout 속성을 가진 마크다운 div입니다. 마크다운 셀에 callout을 만들려면 다음을 입력하세요.

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::

렌더링하면 다음과 같이 표시됩니다.

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Callout 유형과 모양 옵션에 대한 자세한 내용은 Callouts 문서를 참고하세요.

아티클 레이아웃

Quarto 아티클 본문은 기본적으로 약 700픽셀의 너비를 갖습니다. 이 너비는 가독성 최적화를 위해 선택됩니다. 이 경우 문서 여백에 사용 가능한 공간이 생기며, 이를 활용하는 방법이 몇 가지 있습니다.

이 예시에서는 reference-location 옵션으로 각주를 오른쪽 여백에 배치하도록 지정합니다.

또한 column: screen-inset 셀 옵션으로 그림이 화면 전체 폭을 차지하되, 약간의 인셋을 두도록 지정합니다.

---
title: Quarto Layout
format: html
reference-location: margin
---

## Heatmaps

A 2d density estimate of the waiting and eruptions variables from the dataset `faithful`^[See the [documentation](https://rdrr.io/r/datasets/faithful.html) for more details on `faithful` data].

```{r}
#| code-fold: true
#| column: screen-inset
#| fig-width: 10
#| fig-height: 4
library(ggplot2)

ggplot(faithfuld, aes(x = waiting, y = eruptions, fill = density)) +
  geom_tile() +
  scale_fill_viridis_c() +
  theme_bw()
```

---
title: Quarto Layout
format: html
reference-location: margin
---

## Heatmaps

A 2d density estimate of the waiting and eruptions variables from the dataset `faithful`^[See the [documentation](https://rdrr.io/r/datasets/faithful.html) for more details on `faithful` data].

```{python}
#| code-fold: true
#| column: screen-inset
from plotnine import *
from plotnine.data import faithfuld

(
  ggplot(faithfuld, aes(x='waiting', y='eruptions', fill='density'))
  + geom_tile()
  + theme_bw()
  + theme(figure_size=(10, 4))
) 
```

렌더링 결과는 다음과 같습니다.

Document with Quarto Layout title at the top followed by Heatmaps header with text below it. Next to the text is a footnote in the page margin. Below the text is a toggleable code widget to hide/reveal the code followed a wide plot that extends into the right margin.

여백에는 인용, 각주, aside를 배치할 수 있습니다. 또한 그림, 표 또는 다른 콘텐츠에 대한 사용자 정의 열 폭을 지정할 수도 있습니다. 자세한 내용은 아티클 레이아웃 문서를 참고하세요.

더 알아보기

이제 Quarto 사용의 기본을 익혔습니다! 문서를 만들고 커스터마이즈하는 데 익숙해졌다면 다음 주제를 더 탐색해 보세요.

프레젠테이션 — 문서를 만들 때 배운 동일한 문법으로 PowerPoint, Beamer, Revealjs 프레젠테이션을 작성할 수 있습니다.
웹사이트 — 문서 모음을 웹사이트로 배포하세요. 웹사이트는 다양한 탐색 방식과 전체 텍스트 검색을 지원합니다.
블로그 — 소개 페이지, 유연한 글 목록, 카테고리, RSS 피드, 20개 이상의 테마를 갖춘 블로그를 만들 수 있습니다.
책 — 인쇄(PDF, MS Word)와 온라인(HTML, ePub) 형식으로 책과 원고를 만들 수 있습니다.
상호작용 — 독자가 개념과 데이터를 더 깊이 탐색할 수 있도록 대화형 구성 요소를 포함할 수 있습니다.