튜토리얼: 안녕, Quarto

개요

이 튜토리얼에서는 VS Code에서 Quarto를 사용하는 방법을 보여드립니다. 시작하기 전에 Quarto VS Code 확장을 설치하세요. 이 확장은 다음과 같이 Quarto 작업을 향상시키는 다양한 도구를 제공합니다.

  • Quarto 문서의 통합 렌더링 및 미리보기
  • 마크다운 및 임베디드 언어 구문 강조
  • YAML 옵션 자동 완성과 진단
  • 임베디드 언어 자동 완성(예: Python, R, Julia 등)
  • 셀 및 선택 영역 실행을 위한 명령과 키 바인딩

Quarto 확장은 VS Code의 Extensions 탭, Extension Marketplace, Open VSX Registry, 또는 VISX 확장 파일에서 설치할 수 있습니다.

Note

이 튜토리얼은 VS Code에서 일반 텍스트 Quarto .qmd 파일을 편집하는 데 초점을 맞춥니다. 선호도와 작업에 따라 Quarto 문서에 사용할 수 있는 다른 편집 모드가 두 가지 있습니다: 시각적 편집기와 노트북 편집기. 학습을 위해서는 먼저 VS Code 텍스트 편집기로 이 튜토리얼을 따라 한 다음, 기본을 익힌 뒤 다른 편집 모드를 살펴보는 것을 권장합니다.

기본 워크플로

Quarto .qmd 파일은 마크다운과 실행 가능한 코드 셀의 조합으로 구성됩니다. VS Code에서 .qmd 파일을 편집하고 미리보기하면 다음과 같은 모습입니다.

나란히 배치된 두 개의 창. 왼쪽 창은 VS Code에서 열린 qmd 파일입니다. 이 문서는 이 웹사이트의 Getting Started: Welcome 섹션 첫 부분과 동일한 내용이며, 오른쪽 창에서 Quarto가 렌더링한 결과가 보입니다.

왼쪽의 문서가 오른쪽에 보이는 HTML 버전으로 렌더링됩니다. 이것이 Quarto 배포의 기본 모델입니다. 소스 문서를 가져와 HTML, PDF, MS Word 등 다양한 출력 형식으로 렌더링합니다.

이 튜토리얼에서는 matplotlib과 plotly 파이썬 패키지를 사용합니다. 설치 명령은 아래 표에 정리되어 있습니다.

Platform Commands
Mac/Linux 
Terminal
python3 -m pip install jupyter matplotlib plotly
Windows 
Terminal
py -m pip install jupyter matplotlib plotly
Note

이 튜토리얼은 Python을 사용하지만, Julia(IJulia 커널)도 잘 지원됩니다. 자세한 내용은 Julia 사용하기 문서를 참고하세요.

렌더링 및 미리보기

간단한 예제(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()
```

따라 하고 있다면 아직 설치하지 않은 경우 필요한 의존성을 설치하세요.

Platform Commands
Mac/Linux 
Terminal
python3 -m pip install jupyter matplotlib plotly
Windows 
Terminal
py -m pip install jupyter matplotlib plotly

렌더링과 미리보기를 위해 Quarto: Preview 명령을 실행하세요. 또는 Ctrl+Shift+K 단축키나 편집기 오른쪽 상단의 Preview 버튼(Preview icon)을 사용할 수 있습니다.

Visual Studio Code 편집기 상단. 편집기 탭 영역 오른쪽에 Preview 버튼이 보입니다.

Mac에서는 모든 Quarto 단축키의 접두사로 Ctrl 대신 Cmd를 사용해야 합니다.

작동 원리

Quarto로 .qmd 파일을 렌더링하면 실행 가능한 코드 블록이 Jupyter에서 처리되고, 코드/마크다운/출력의 조합이 일반 마크다운으로 변환됩니다. 그다음 이 마크다운을 Pandoc이 처리하여 최종 형식을 생성합니다.

qmd 파일 -> Jupyter -> md -> pandoc -> PDF/MS Word/HTML로 이어지는 워크플로 다이어그램.

저작

간단한 변경을 해보고 다시 렌더링해 보겠습니다.

  1. theta를 정의하는 코드를 다음과 같이 변경하세요.

    theta = 4 * np.pi * r

  2. 파일을 다시 렌더링합니다(Quarto: Preview 또는 Ctrl+Shift+K 사용). 문서가 렌더링되고 브라우저 미리보기가 업데이트됩니다.

이것이 Quarto 저작의 기본 워크플로입니다.

렌더링 시에는 파일을 저장할 필요가 없습니다(렌더링 시 자동으로 저장됩니다). 원한다면 문서를 저장할 때마다 렌더링되도록 Quarto 확장을 구성할 수 있습니다. 자세한 내용은 Render on Save 문서를 참고하세요.

셀 실행

코드 셀을 반복 작업할 때 문서를 완전히 렌더링할 필요는 없습니다. 코드 셀 위에 Run Cell 버튼이 있는 것을 확인할 수 있습니다. 해당 버튼을 클릭하면 셀이 실행되며(출력은 Jupyter 인터랙티브 콘솔에 나란히 표시됩니다):

VS Code에서 두 개의 패널이 열려 있으며, 오른쪽에는 vscode.qmd 소스 코드가, 왼쪽에는 해당 코드의 인터랙티브 출력이 표시됩니다.

현재 셀은 Ctrl+Shift+Enter, 현재 줄(들)은 Ctrl+Enter, 이전 셀은 Ctrl+Alt+P로 실행할 수 있습니다(Mac에서는 모든 Quarto 단축키의 접두사로 Ctrl 대신 Cmd를 사용합니다).

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과/또는 코드를 변경한 다음 다시 렌더링해 업데이트된 미리보기를 확인하세요.

출력을 원하는 방식으로 조정할 수 있는 다양한 셀 옵션이 있습니다. 이 옵션들은 다음 튜토리얼에서 더 자세히 다룹니다.

Note

그림에서 특히 유용한 셀 옵션 중 하나는 fig-alt입니다. 시각 장애가 있는 사용자를 위해 이미지에 대체 텍스트를 추가할 수 있습니다. 자세한 내용은 Amy Cesal의 데이터 시각화를 위한 대체 텍스트 작성하기 글을 참고하세요.

외부 미리보기

이 튜토리얼에서는 VS Code 내부의 패널에서 렌더링된 출력을 미리보았습니다. 외부 브라우저에서 미리보기를 사용하거나(또는 렌더링 시 미리보기를 전혀 띄우지 않으려면) Preview Type 옵션을 사용해 동작을 변경할 수 있습니다.

VS Code 설정 화면에서 'quarto preview type'을 검색한 모습. 사용자 설정에 Quarto > Render: Preview Type 항목이 있고, 렌더링 후 미리보기 위치를 선택하는 드롭다운이 있습니다. 기본값 internal이 선택되어 있으며, 다른 옵션으로 external과 none이 있습니다.

다음 단계

이제 Quarto 문서를 만들고 작성하는 기본을 익혔습니다. 다음 튜토리얼에서 Quarto를 더 깊이 있게 살펴보세요:

  • 튜토리얼: 계산 — 실행 가능한 코드 블록의 동작과 출력을 원하는 방식으로 조정하는 방법을 배웁니다.

  • 튜토리얼: 작성 — 출력 형식과 인용, 상호 참조, 고급 레이아웃 같은 기술 문서 작성 기능을 더 알아봅니다.

또한 VS Code에서 사용할 수 있는 다른 Quarto 편집 모드도 살펴보세요.