튜토리얼: 안녕, Quarto

도구 선택

개요

Quarto는 Posit의 R Markdown을 계승한 다국어 차세대 버전으로, 수십 가지의 새로운 기능과 역량을 제공하면서도 기존 Rmd 파일 대부분을 수정 없이 렌더링할 수 있습니다.

이 튜토리얼에서는 RStudio에서 Quarto를 사용하는 방법을 보여드립니다. 일반적인 계산 문서(R Markdown 등)와 마찬가지로 RStudio에서 코드와 마크다운을 편집하고, 작업하면서 Viewer 탭에서 렌더링된 문서를 미리봅니다.

아래는 확장자가 .qmd인 Quarto 문서(왼쪽)와 HTML로 렌더링된 버전(오른쪽)입니다. PDF, MS Word 등 다른 형식으로도 렌더링할 수 있습니다.

왼쪽에 "Penguins, meet Quarto!"라는 제목의 Quarto 문서가 열려 있고, 오른쪽에 렌더링된 문서가 보이는 RStudio 화면.

이것이 Quarto 배포의 기본 모델입니다. 소스 문서를 다양한 출력 형식으로 렌더링합니다.

튜토리얼을 시작하기 전에 Quarto를 영상으로 소개받고 싶다면 Get Started with Quarto를 시청하세요. 실행 가능한 코드 청크로 Quarto 문서를 작성하고, 여러 형식으로 렌더링하며, revealjs 프레젠테이션을 만들고, 웹사이트를 만들고, QuartoPub에 배포하는 과정을 미리볼 수 있습니다.

자신의 환경에서 이 튜토리얼을 따라 하려면 아래 단계를 수행하세요.

RStudio 최신 릴리스를 다운로드해 설치합니다.

Download RStudio
tidyverse와 palmerpenguins 패키지가 설치되어 있는지 확인합니다.
```
install.packages("tidyverse")
install.packages("palmerpenguins")
```
아래 Quarto 문서(.qmd)를 다운로드해 RStudio에서 열고 Render를 클릭합니다.

Download hello.qmd

렌더링

RStudio IDE의 Render 버튼을 사용하면 클릭 한 번 또는 단축키(⇧⌘K)로 파일을 렌더링하고 출력 미리보기를 확인할 수 있습니다.

RStudio 텍스트 편집기 상단에서 Render 버튼이 보라색 박스로 강조되어 있습니다.

저장할 때마다 자동으로 렌더링하고 싶다면 편집기 도구 모음의 Render on Save 옵션을 체크하세요. 문서를 다시 렌더링할 때마다 미리보기가 업데이트됩니다. HTML과 PDF 출력 모두 나란히 미리보기가 가능합니다.

RStudio 텍스트 편집기 상단에서 Render on Save 체크박스가 체크되어 있고 보라색 박스로 강조되어 있습니다.

문서는 quarto 패키지를 통해 R 콘솔에서 렌더링할 수도 있습니다.

install.packages("quarto")
quarto::quarto_render("hello.qmd")

렌더링 시 Quarto는 .qmd 파일의 선택된 텍스트, 코드, 결과를 포함하는 새 파일을 생성합니다. 새 파일은 HTML, PDF, MS Word 문서, 프레젠테이션, 웹사이트, 책, 인터랙티브 문서, 기타 형식일 수 있습니다.

저작

아래 이미지에서는 RStudio 편집기의 두 모드(왼쪽의 시각적 모드, 오른쪽의 소스 모드)에서 같은 문서를 볼 수 있습니다. RStudio의 시각적 편집기는 마크다운에 대해 WYSIWYM 저작 경험을 제공합니다. 서식(예: 굵게 강조)은 도구 모음, 단축키(⌘B), 또는 마크다운 구문(**bold**)으로 적용할 수 있습니다. 문서의 기본 텍스트 소스는 자동으로 작성되며, 소스 모드로 전환해 언제든 확인/수정할 수 있습니다. 편집기 도구 모음에서 Source와 Visual을 클릭하거나 단축키 ⌘⇧ F4를 사용해 두 모드를 전환할 수 있습니다.

왼쪽: 시각적 편집기의 문서. 오른쪽: 같은 문서의 소스 편집기. 시각/소스 토글이 현재 상태를 강조 표시합니다. 문서는 이전 이미지에 나온 "Hello Quarto" 문서입니다.

이제 Quarto 문서의 내용을 살펴보겠습니다. 파일에는 세 가지 유형의 콘텐츠가 있습니다: YAML 헤더, 코드 청크, 마크다운 텍스트.

YAML 헤더

양쪽 끝이 세 개의 대시(---)로 구분된 (선택적) YAML 헤더입니다.

---
title: "Hello, Quarto"
format: html
editor: visual
---

렌더링하면 title인 “Hello, Quarto”가 문서 상단에 더 큰 글꼴로 표시됩니다. 다른 두 YAML 필드는 출력이 html format이어야 하고 문서가 기본적으로 visual editor에서 열려야 함을 나타냅니다.

YAML의 기본 문법은 key: value 형식의 키-값 쌍입니다. 문서 헤더에서 자주 보이는 다른 YAML 필드로는 author, subtitle, date 같은 메타데이터와 theme, fontcolor, fig-width 같은 사용자화 옵션이 있습니다. HTML 문서에 사용 가능한 YAML 필드는 여기에서 확인할 수 있습니다. 문서 형식에 따라 YAML 필드는 달라집니다. 예를 들어 PDF 문서의 YAML 필드는 여기, MS Word의 YAML 필드는 여기를 참고하세요.

코드 청크

{r}로 식별되는 R 코드 청크이며, 줄 맨 앞의 #|로 표시되는 YAML 스타일의 (선택적) 청크 옵션을 포함합니다.

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(palmerpenguins)
```

이 경우 코드 청크의 label은 load-packages이고, include를 false로 설정해 청크 자체나 출력이 렌더링된 문서에 나타나지 않도록 했습니다.

코드 청크의 결과를 보기 위해 문서를 완전히 렌더링하는 것 외에도, RStudio 편집기에서 아이콘이나 단축키(⇧⌘⏎)를 사용해 각 코드 청크를 대화형으로 실행할 수 있습니다. RStudio는 코드를 실행하고, 설정에 따라 파일 안에 인라인으로 또는 콘솔에 결과를 표시합니다.

배경에는 hello.qmd의 plot-penguins 청크가 보이며, 그 위에 출력(펭귄의 부리 길이와 지느러미 길이의 관계를 종별 색으로 표시한 산점도)이 일부 겹쳐 표시됩니다. 코드 청크 실행 버튼이 강조되어 있고, 버튼을 클릭하면 플롯이 생성됨을 화살표로 표시합니다.

마크다운 텍스트

섹션 제목, 하이퍼링크, 임베디드 이미지, 인라인 코드 청크 등 서식이 포함된 텍스트입니다.

"Penguins, meet Quarto!" 예제 문서의 텍스트 부분. "Text"라는 주석이 표시되어 있습니다.

Quarto는 텍스트에 마크다운 문법을 사용합니다. 시각적 편집기를 사용하면 제목 추가, 굵은 텍스트, 표 삽입 등을 메뉴와 단축키로 할 수 있어 많은 마크다운 문법을 외울 필요가 없습니다. 소스 편집기를 사용할 경우 ##, **bold** 같은 마크다운 표현으로 동일한 작업을 할 수 있습니다.

작동 원리

Quarto 문서를 렌더링할 때 먼저 knitr가 모든 코드 청크를 실행하고 코드와 출력이 포함된 새 마크다운(.md) 문서를 생성합니다. 생성된 마크다운 파일은 pandoc에서 처리되어 최종 형식이 만들어집니다. Render 버튼은 이 과정을 올바른 순서로 실행하도록 묶어줍니다.

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

다음 단계

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

튜토리얼: 계산 — 실행 가능한 코드 블록의 동작과 출력을 원하는 방식으로 조정하는 방법을 배웁니다.
튜토리얼: 작성 — 출력 형식과 인용, 상호 참조, 고급 레이아웃 같은 기술 문서 작성 기능을 더 알아봅니다.