튜토리얼: 안녕, Quarto
Positron
VS Code
Jupyter
RStudio
Neovim
에디터
개요
이 튜토리얼에서는 선호하는 텍스트 편집기에서 Quarto를 사용하는 방법을 보여드립니다. 일반 텍스트 .qmd 파일을 편집하고, 작업하면서 렌더링된 문서를 웹 브라우저에서 미리봅니다.
아래는 전체 흐름의 개요입니다.
왼쪽의 노트북이 오른쪽에 보이는 HTML 버전으로 렌더링됩니다. 이것이 Quarto 배포의 기본 모델입니다. 소스 문서(여기서는 노트북)를 가져와 HTML, PDF, MS Word 등 다양한 출력 형식으로 렌더링합니다.
이 튜토리얼에서는 matplotlib과 plotly 파이썬 패키지를 사용합니다. 설치 명령은 아래 표에 정리되어 있습니다.
| Platform | Commands |
|---|---|
| Mac/Linux | Terminal |
| Windows | Terminal |
이 튜토리얼은 Python을 사용하지만, Julia(IJulia 커널)도 잘 지원됩니다. 자세한 내용은 Julia 사용하기 문서를 참고하세요.
편집기 모드
VS Code를 사용한다면 먼저 VS Code용 Quarto 확장을 설치하세요. 이 확장은 마크다운과 임베디드 언어 구문 강조, 임베디드 언어 자동 완성(예: Python, R, Julia, LaTeX 등), 셀 및 선택 영역 실행을 위한 명령과 키 바인딩 등을 제공합니다.
다른 편집기에서도 사용할 수 있는 Quarto 구문 강조 모드가 있습니다.
| Editor | Extension |
|---|---|
| Emacs | https://github.com/quarto-dev/quarto-emacs |
| Vim / Neovim | https://github.com/quarto-dev/quarto-vim |
| Neovim | https://github.com/quarto-dev/quarto-nvim |
| Sublime Text | https://github.com/quarto-dev/quarto-sublime |
렌더링
간단한 예제(hello.qmd)를 몇 가지 형식으로 렌더링하는 것부터 시작하겠습니다. 자신의 환경에서 단계별로 따라 하려면 hello.qmd라는 새 파일을 만들고 다음 내용을 복사해 넣으세요.
---
title: "Quarto Basics"
format:
html:
code-fold: true
jupyter: python3
---
For a demonstration of a line plot on a polar axis, see @fig-polar.
```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"
import numpy as np
import matplotlib.pyplot as plt
r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
subplot_kw = {'projection': 'polar'}
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```다음으로 터미널을 열고 hello.qmd가 있는 디렉터리로 이동하세요.
이제 문서를 몇 가지 형식으로 렌더링해 보겠습니다.
Terminal
quarto render hello.qmd --to html
quarto render hello.qmd --to docx대상 파일(이 경우 hello.qmd)은 항상 명령줄 인자의 첫 번째에 있어야 합니다.
Quarto로 .qmd 파일을 렌더링하면 실행 가능한 코드 블록이 Jupyter에서 처리되고, 코드/마크다운/출력의 조합이 일반 마크다운으로 변환됩니다. 그다음 이 마크다운을 Pandoc이 처리하여 최종 형식을 생성합니다.
저작
quarto render 명령은 배포용 문서의 최종 버전을 만드는 데 사용됩니다. 하지만 저작 단계에서는 quarto preview 명령을 사용합니다. 지금 터미널에서 hello.qmd로 실행해 보세요.
Terminal
quarto preview hello.qmd이 명령은 문서를 렌더링한 다음 웹 브라우저에 표시합니다.
변경 사항을 보면서 작업할 수 있도록 편집기와 브라우저 미리보기를 나란히 배치하는 것이 좋습니다.
라이브 미리보기를 확인해 보겠습니다.
theta를 정의하는 코드를 다음과 같이 변경하세요.theta = 4 * np.pi * r파일을 저장합니다. 문서가 다시 렌더링되고 브라우저 미리보기가 업데이트됩니다.
이것이 Quarto 저작의 기본 워크플로입니다.
hello.qmd에는 여러 유형의 콘텐츠가 있으니 각각을 조금씩 살펴보겠습니다.
YAML 옵션
파일 맨 위에는 문서 수준 옵션이 담긴 YAML 블록이 있습니다.
---
title: "Quarto Basics"
format:
html:
code-fold: true
jupyter: python3
---code-fold 옵션을 false로 바꿔 보세요.
format:
html:
code-fold: false그런 다음 파일을 저장하세요. 이전에는 Code 버튼으로 숨겨져 있던 코드가 이제 플롯 위에 표시되는 것을 확인할 수 있습니다.
마크다운
서술형 콘텐츠는 마크다운으로 작성합니다. 여기서는 제목과 아래 코드 셀에서 생성된 그림에 대한 상호 참조를 지정합니다.
## Polar Axis
For a demonstration of a line plot on a polar axis, see @fig-polar.제목을 바꿔 저장하면 미리보기가 새 제목 텍스트로 업데이트됩니다.
코드 셀
코드 셀에는 렌더링 중 실행될 코드가 포함되며, 출력(및 선택적으로 코드)이 렌더링된 문서에 포함됩니다.
```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"
import numpy as np
import matplotlib.pyplot as plt
r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
subplot_kw = {'projection': 'polar'}
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```여기 제시된 Matplotlib 코드는 익숙할 것입니다. 하지만 코드 셀 상단에 있는 label과 fig-cap 옵션은 생소할 수 있습니다. 셀 옵션은 특수 접두사가 붙은 주석(#|)으로 YAML 형식으로 작성합니다.
이 예제에서는 셀 옵션을 사용해 그림을 상호 참조할 수 있도록 했습니다. fig-cap과/또는 코드를 변경하고 셀을 실행한 뒤 파일을 저장해 업데이트된 미리보기를 확인하세요.
출력을 원하는 방식으로 조정할 수 있는 다양한 셀 옵션이 있습니다. 이 옵션들은 다음 튜토리얼에서 더 자세히 다룹니다.
그림에서 특히 유용한 셀 옵션 중 하나는 fig-alt입니다. 시각 장애가 있는 사용자를 위해 이미지에 대체 텍스트를 추가할 수 있습니다. 자세한 내용은 Amy Cesal의 데이터 시각화를 위한 대체 텍스트 작성하기 글을 참고하세요.
다음 단계
이제 Quarto 문서를 만들고 작성하는 기본을 익혔습니다. 다음 튜토리얼에서 Quarto를 더 깊이 있게 살펴보세요: