튜토리얼: 안녕, Quarto
Positron
VS Code
Jupyter
RStudio
Neovim
에디터
이 튜토리얼은 R 또는 Python 코드 예제를 사용해 따라갈 수 있습니다. 선호하는 언어를 선택하세요.
R 예제를 보도록 선택했습니다. 안내서 전반에서 언제든지 Python으로 전환할 수 있습니다.
Python 예제를 보도록 선택했습니다. 안내서 전반에서 언제든지 R로 전환할 수 있습니다.
개요
Quarto는 코드와 서술을 엮어 고품질 문서, 프레젠테이션, 웹사이트 등을 만들어내는 오픈 소스 과학/기술 출판 시스템입니다. 이 튜토리얼에서는 Positron에서 Quarto를 사용하는 방법을 배웁니다.
Positron은 Quarto와 즉시 함께 사용할 수 있도록 준비되어 있습니다. Quarto CLI와 Quarto VS Code 확장이 기본으로 포함되어 있습니다.
또한 Quarto 작업을 향상시키는 다양한 도구가 포함되어 있습니다.
Quarto 문서의 통합 렌더링 및 미리보기
Quarto 옵션 자동 완성과 진단
Quarto 문서 안의 코드에 대한 Positron의 완전한 R/Python 지원(콘솔에서의 대화형 실행, 코드 자동 완성, 도움말, 진단 등)
다음은 Positron에서 열린 샘플 Quarto 문서 hello.qmd로, 편집과 미리보기가 나란히 이루어지는 경험을 보여줍니다.
이 페이지에서 다음 내용을 배우게 됩니다.
Positron에서 Quarto 문서를 편집하고 미리보는 기본 워크플로
Quarto 문서를 구성하는 세 요소(헤더, 코드 셀, 마크다운)와 이들이 렌더링된 출력으로 결합되는 방식
설정
자신의 환경에서 이 튜토리얼을 따라 하려면 아래 단계를 수행하세요.
rmarkdown,tidyverse,palmerpenguins패키지가 설치되어 있는지 확인하세요.install.packages("rmarkdown") install.packages("tidyverse") install.packages("palmerpenguins")아래 Quarto 문서(
hello.qmd)를 다운로드해 Positron에서 여세요.
원하는 방법으로
jupyter와plotnine패키지를 설치하세요. 예를 들어pip를 사용하면 다음과 같습니다.pip install jupyter plotnine아래 Quarto 문서(
hello.qmd)를 다운로드해 Positron에서 여세요.
기본 워크플로
확장자가 .qmd인 Quarto 문서는 일반 텍스트 형식이며 Positron의 Editor 패널에서 열립니다.
문서를 미리보려면 Quarto: Preview 명령을 실행하세요. 또는 단축키 를 사용하거나, 편집기 도구 모음의 Preview 버튼(
)을 사용할 수 있습니다.
Quarto가 문서를 처리한 뒤 Viewer 패널에서 출력이 미리보기로 표시됩니다.
Quarto: Preview 명령을 다시 실행할 때마다 미리보기가 업데이트됩니다. 예를 들어 섹션 제목 ## Meet the penguins를 ## Meet the Palmer penguins로 바꾸고 Quarto: Preview를 다시 실행해 보세요. Viewer의 미리보기가 변경 내용을 반영합니다.
문서를 저장할 때마다 미리보기를 업데이트하고 싶다면 편집기 도구 모음의 Render on Save 체크박스를 선택하세요.
렌더링
문서 hello.qmd는 마크다운과 실행 가능한 코드 셀로 구성됩니다. Quarto는 이 소스 문서에서 코드 실행 결과와 마크다운을 결합한 새 파일을 만드는 과정을 render라고 부릅니다. hello.qmd를 렌더링하면 HTML 문서인 hello.html이 생성되지만, PDF, MS Word 문서, 프레젠테이션, 웹사이트, 책, 인터랙티브 문서, 기타 형식으로도 렌더링할 수 있습니다.
이것이 Quarto 배포의 기본 모델입니다. 코드와 서술이 결합된 소스 문서를 다양한 출력 형식으로 렌더링하는 것입니다.
Quarto: Preview 명령은 두 가지 작업을 포함합니다. 문서를 렌더링하고, 결과 파일을 미리보는 것입니다. HTML과 PDF 형식은 Positron의 Viewer 패널에서 나란히 미리보기로 열립니다. MS Word 같은 다른 형식은 외부에서 열립니다.
Quarto: Render Document 명령을 실행하면 미리보기 없이 문서만 렌더링할 수도 있습니다.
Quarto: Preview 명령을 실행하면 터미널에서 quarto preview가 실행되는 것을 확인할 수 있습니다.
Quarto 확장은 터미널에서 quarto 명령을 직접 실행하는 대신 편리한 Positron 명령을 제공하지만, 원하면 직접 명령을 실행할 수도 있습니다.
저작
이제 Quarto 문서의 내용을 살펴보겠습니다. 파일에는 세 가지 유형의 콘텐츠가 있습니다. 헤더, 실행 가능한 코드 셀, 그리고 마크다운 텍스트입니다.
문서 헤더
파일 맨 위에는 세 개의 대시(---)로 둘러싸인 문서 헤더가 있습니다.
---
title: Hello, Quarto
format: html
---헤더 안에서는 YAML을 사용해 문서 수준의 옵션을 지정합니다. YAML의 기본 문법은 key: value 형식의 키-값 쌍입니다.
이 예에서는 title이 “Hello, Quarto”로 설정되고 format이 html로 설정되어 있습니다. 렌더링하면 title이 문서 상단에 더 큰 글꼴로 표시됩니다. format 필드는 출력 대상 형식을 나타냅니다.
문서 헤더에서 자주 보이는 다른 옵션으로는 author, subtitle, date 같은 메타데이터와 theme, fontcolor, fig-width 같은 사용자화 옵션이 있습니다. 사용 가능한 옵션은 출력 형식에 따라 달라지며 참조 문서에 나열되어 있습니다. 예: HTML 옵션, PDF 옵션, MS Word 옵션
코드 셀
코드 셀에는 렌더링 중 실행될 코드가 포함되며, 출력(및 선택적으로 코드)이 렌더링된 문서에 포함됩니다.
코드 셀은 {r}로 식별됩니다.
```{r}
#| label: load-packages
#| include: false
library(tidyverse)
library(palmerpenguins)
```코드 셀은 {python}으로 식별됩니다.
```{python}
#| label: load-packages
#| include: false
from plotnine import *
from plotnine.data import penguins
```코드 셀 옵션은 #|로 시작하는 특수 주석을 사용해 코드 셀 상단에 설정합니다. 옵션 자체는 YAML 문법으로 지정합니다. 이 예에서 코드 셀의 label은 load-packages이고, include는 false로 설정되어 코드와 출력이 렌더링된 문서에 나타나지 않음을 의미합니다. 출력을 원하는 방식으로 조정할 수 있는 다양한 코드 셀 옵션이 있으며, 다음 튜토리얼인 계산에서 더 알아볼 수 있습니다.
코드 셀 결과를 보기 위해 문서를 완전히 렌더링하는 것 외에도 각 코드 셀을 대화형으로 실행할 수 있습니다. Quarto: Run Cell 명령을 실행하거나 단축키()를 사용하거나, Editor에서 셀 바로 위의 Run Cell을 클릭하세요. Positron은 콘솔에서 코드를 실행하고 결과를 표시합니다.
마크다운 텍스트
서술형 콘텐츠는 마크다운으로 작성합니다. 예를 들어 다음 발췌문에는 섹션 제목(## heading), 코드 형식 텍스트(`code`), 그리고 링크([text](url))가 포함되어 있습니다.
## Meet the Palmer penguins
The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins) package contains...## Meet the Palmer penguins
The `penguins` data from the [plotnine](https://plotnine.org/reference/penguins.html) package contains...Quarto는 기본 텍스트 서식, 표, 이미지용 마크다운 문법뿐 아니라 인용, 상호 참조, 수식 같은 고급 기능도 지원합니다. 마크다운에 대한 자세한 내용은 마크다운 기초 문서를 참고하세요.
작동 원리
Quarto 문서에 실행 가능한 코드 셀이 포함되면 Quarto는 이를 실행하기 위해 엔진을 사용합니다. 이 튜토리얼을 R로 따라왔다면 knitr 엔진을 사용하고 있습니다. Python으로 따라왔다면 jupyter 엔진을 사용하고 있습니다. Quarto가 엔진을 선택하는 방식은 엔진 바인딩 문서에서 확인할 수 있습니다.
Quarto는 R과 Python 외에도 Julia(julia 엔진 또는 jupyter 엔진)와 Observable JS 등 다양한 언어를 지원합니다.
다음 단계
이제 Quarto 문서를 만들고 작성하는 기본을 익혔습니다. 다음 튜토리얼에서 Quarto를 더 깊이 있게 살펴보세요: