튜토리얼: 저작

도구 선택

개요

이 튜토리얼에서는 RStudio에서 Quarto 문서를 작성하는 방법을 안내합니다. 특히 동일한 소스 코드로 만들 수 있는 다양한 문서 형식을 살펴보고 목차, 수식, 인용 등 구성 요소를 추가하는 방법을 보여드립니다. RStudio의 시각적 마크다운 편집기는 이러한 작업을 더 쉽게 해주므로 이 튜토리얼에서 이를 강조하지만, 소스 편집기에서도 동일한 작업을 수행할 수 있습니다.

자신의 환경에서 단계별로 따라 하려면 RStudio의 최신 릴리스를 설치하세요.

출력 형식

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

형식 옵션

새 문서를 만들 때 렌더링할 형식을 선택할 수 있습니다. 새 문서를 만들려면 File > New File > Quarto Document…로 이동하세요. 또는 Ctrl+Shift+P로 명령 팔레트를 열고 Create a new Quarto document를 검색한 다음 Enter를 누르세요.

Title 필드에 문서 제목을 입력하고(예: 아래 스크린샷에는 “Housing Prices”가 보입니다), Author 필드에 이름을 추가하세요. 다음으로 문서의 출력 형식을 선택합니다. 기본값으로 RStudio는 HTML 출력을 제안합니다. 우선 이 기본값을 유지하겠습니다.

새 문서 만들기 팝업 메뉴. Title 필드에 "Housing Prices"를 입력했고 Author 필드에는 "Mine Çetinkaya-Rundel"이 보입니다. 라디오 버튼으로 HTML 형식이 선택되어 있습니다. 나머지는 기본값(예: Engine은 Knitr, Use visual markdown editor 체크됨)입니다.

다음 YAML로 새 문서가 생성됩니다.

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
---

형식 선택(HTML)이 YAML에 반영되지 않은 점에 주의하세요. 이는 Quarto 문서의 기본 출력 형식이기 때문입니다. 하지만 YAML을 직접 편집하여 출력 형식을 PDF(pdf)나 MS Word(docx)로 변경할 수 있습니다. 아래와 같이 문서의 YAML에 format: pdf를 추가하세요.

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
format: pdf
---

안타깝게도 이 문서는 내용이 없어서 렌더링하더라도 흥미로운 결과를 얻기 어렵습니다. 이 튜토리얼에서 강조하려는 기능을 좀 더 쉽게 보여주기 위해, 빈 문서를 닫고 약간의 내용이 있는 문서로 시작하겠습니다. 자신의 환경에서 단계별로 따라 하려면 아래 Quarto 문서(.qmd)를 다운로드해 RStudio에서 여세요.

Download authoring.qmd

format: pdf에 LaTeX 필요

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

Terminal

quarto install tinytex

다른 LaTeX 배포판과 PDF 컴파일 엔진 사용 방법은 PDF 엔진 문서를 참고하세요.

LaTeX 설정이 완료되면 Render를 클릭하거나 단축키 ⇧⌘K를 사용하세요. 변경 사항을 실시간으로 미리 보려면 Render on Save 체크박스도 활성화하는 것을 권장합니다. 아래처럼 RStudio의 Viewer에서 렌더링된 PDF가 표시되어야 합니다.

RStudio에서 authoring.qmd가 열려 있는 화면. 왼쪽에는 시각적 편집기의 소스 코드가 있고, 오른쪽에는 Viewer에 렌더링된 PDF가 보입니다.

다음으로 YAML에 옵션을 추가해 보겠습니다. 예를 들어 코드 청크에 줄 번호를 표시하려면 code-line-numbers: true를 추가합니다. 아래처럼 문서의 YAML에 이 옵션을 추가하되, 들여쓰기 규칙에 유의하세요. format: 아래에 출력 형식 pdf가 두 칸 들여쓰기로 들어가며, 뒤에 :를 붙여 해당 형식의 추가 옵션이 이어짐을 나타냅니다. 그 다음 줄에서 두 칸을 더 들여 code-line-numbers: true를 추가합니다.

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
format:
  pdf:
    code-line-numbers: true
---

앞에서 Render on Save를 체크했다면 이 변경 후 문서를 저장하기만 해도 실시간 미리 보기가 갱신됩니다. 그렇지 않다면 렌더링을 실행해 변경 사항을 확인하세요. 아래처럼 목차가 포함된 결과가 나타납니다.

authoring.qmd를 PDF로 렌더링한 결과. 각 코드 청크 줄 옆에 줄 번호가 표시되어 있습니다.

이 튜토리얼에서는 자세히 다루지 않지만, 매우 흥미로운 형식 옵션 중 하나가 revealjs입니다. 맞습니다. Quarto로 프레젠테이션도 만들 수 있습니다! 사실 Quarto는 다양한 프레젠테이션 형식을 지원하며, HTML 슬라이드용 revealjs, PowerPoint용 pptx, LaTeX/PDF용 beamer 등이 포함됩니다. 프레젠테이션 문서에서 Quarto로 슬라이드 덱을 만드는 과정을 자세히 안내합니다.

여러 형식

작성하는 문서 중 일부는 단일 출력 형식만 필요하지만, 많은 경우 여러 형식을 지원하는 것이 바람직합니다. 문서에 html과 docx 형식을 추가하고 각 형식에 대한 옵션을 조금씩 변경해 봅시다.

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
highlight-style: pygments
format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default
---

정말 많은 내용이죠! 조금씩 나눠서 살펴보겠습니다. 처음 두 줄은 출력 형식과 무관한 문서 메타데이터입니다.

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
---

다음 줄은 모든 형식에 적용되는 문서 형식 옵션으로, 그래서 최상위 수준에 지정됩니다.

---
highlight-style: pygments
---

이후 format 옵션에서 형식별 옵션을 지정합니다.

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

html과 pdf 형식은 각각 몇 가지 옵션을 제공합니다. 예를 들어 HTML 출력에서는 사용자가 코드를 표시하거나 숨길 수 있도록 code-fold: true를 설정하고, 수식 렌더링에는 katex를 사용합니다. PDF에서는 여백을 정의합니다. docx 형식은 조금 다르게 docx: default를 지정합니다. 이는 해당 형식의 기본 옵션을 그대로 사용하겠다는 뜻입니다.

렌더링

RStudio에서 Render 버튼을 클릭하거나 단축키 ⇧⌘K를 사용하면 YAML에 나열된 첫 번째 형식으로 문서가 렌더링됩니다.

authoring.qmd를 HTML로 렌더링한 결과. 목차가 없고 코드 청크가 접혀 있어 코드가 숨겨져 있습니다.

또한 Render 버튼에는 드롭다운 메뉴가 있어 YAML front matter에 나열된 어떤 형식으로도 렌더링할 수 있습니다.

모든 형식으로 렌더링하려면 R에서 Quarto CLI를 사용할 수 있게 해주는 quarto 패키지를 이용할 수 있습니다. 예를 들어 현재 문서를 렌더링하려면 quarto::quarto_render()를 사용합니다. 또한 렌더링할 문서 이름과 출력 형식(들)을 지정할 수도 있습니다.

quarto::quarto_render(
  "authoring.qmd", 
  output_format = c("pdf", "html", "docx")
)

그러면 Files 패널에 다음과 같이 세 개의 새 파일이 나타납니다.

authoring.docx
authoring.html
authoring.pdf

RStudio Files 패널. authoring이라는 이름의 문서가 docx, html, pdf, qmd 확장자로 각각 보입니다.

섹션

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

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
toc: true
number-sections: true
highlight-style: pygments
format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default
---

이 문서를 HTML로 렌더링하면 아래처럼 보입니다.

authoring.qmd를 HTML로 렌더링한 결과. 번호가 매겨진 섹션과 우측 상단의 목차가 보입니다. 목차에는 Introduction, Exploratory data analysis(하위 섹션 Data visualization, Summary statistics), Modeling의 세 섹션이 표시됩니다.

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

수식

시각적 편집기 모드를 사용하는 경우 Insert Anything 도구를 이용해 RStudio에서 Quarto 문서에 LaTeX 수식을 추가할 수 있습니다. 빈 블록 시작에서 /를 누르거나, 다른 위치에서 Cmd+/로 도구를 열 수 있습니다.

표시 수식(새 줄)은 $$…$$로, 인라인 수식은 $…$ 로 감쌉니다. 문서에 다음을 표시 수식으로 추가하세요.

price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon

RStudio는 입력과 동시에 튜토리얼의 렌더링 결과를 표시합니다. 자세한 내용은 마크다운 수식 문서를 참고하세요.

인용

Insert Anything 도구를 사용해 문서에 인용을 삽입할 수도 있습니다.

시각적 편집기에서 Insert Anything 도구로 인용을 삽입하는 모습.

다음 창에서 문서의 참고문헌, Zotero 개인/그룹 라이브러리, DOI (문서 객체 식별자) 참조, 그리고 Crossref, DataCite, PubMed 검색 등 다양한 출처에서 인용을 추가할 수 있습니다. 시각적 편집기의 인용 기능에 대해서는 여기를 참고하세요.

왼쪽에서 From DOI를 선택하고 검색창에 DOI 10.1093/comjnl/27.2.97를 붙여 넣은 뒤 Search를 누르세요. 그런 다음 찾은 참고문헌을 선택하고 Insert를 눌러 문서에 삽입합니다.

문서에 처음 인용을 추가하는 경우, RStudio가 자동으로 참고문헌 파일을 만들어 줍니다. 이 파일은 기본적으로 references.bib이며, RStudio는 문서 YAML 메타데이터에 bibliography: references.bib도 추가합니다.

참고문헌 항목은 @citeid 구문으로 인용합니다. 다음 텍스트를 문서에 추가하세요.

We're going to do this analysis using literate programming [@knuth1984].

참고문헌은 문서 끝에 포함되므로 노트북 하단에 ## References 제목을 추가합니다. 세 개의 점(…)을 클릭해 속성을 편집하여 이 섹션에 .unnumbered 클래스를 추가할 수도 있습니다.

References 섹션 제목의 속성 편집 창. 세 개의 점 메뉴를 클릭하면 이 창을 열 수 있음을 보여줍니다.

다음은 관련 부분을 강조하기 위해 중간 섹션을 생략한 렌더링 결과입니다.

문서 끝에 단일 인용과 References 섹션이 있는 모습.

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

상호 참조

상호 참조를 사용하면 그림, 표, 수식, 섹션에 대한 번호 및 하이퍼링크를 제공해 독자가 문서를 더 쉽게 탐색할 수 있습니다. 상호 참조 가능한 대상에는 일반적으로 레이블(고유 식별자)과 캡션이 필요합니다.

예를 들어 앞서 추가한 수식에 레이블을 붙이려면, 세 점을 클릭해 속성을 편집하고 #eq-로 시작하는 제안 형식을 사용해 수식에 레이블을 지정하세요.

시각적 편집기로 수식에 레이블을 추가하는 모습. 레이블은 #eq-slr로 지정되어 있습니다.

그다음 시각적 편집기의 Insert Anything 도구를 사용해 상호 참조를 추가합니다. 예를 들어 상호 참조를 맥락화하기 위해 “We can fit a simple linear regression model of the form shown in” 같은 문장을 추가한 뒤, 문장 끝에 참조를 삽입할 수 있습니다.

시각적 편집기의 Insert Anything 도구로 상호 참조를 삽입하는 모습.

Insert Cross Reference 메뉴에서 왼쪽의 대상 유형을 선택하고, 앞서 레이블을 지정한 수식을 선택하세요.

또는 시각적 편집기에서 참조할 수식의 레이블을 입력하기 시작하면 자동완성 도구가 상호 참조 후보를 보여줍니다.

수식 레이블을 입력하기 시작해 상호 참조를 추가하는 모습.

아래는 작업 중인 문서의 일부를 사용해 다양한 유형의 상호 참조를 보여주는 예시입니다.

We present the results of exploratory data analysis in @sec-eda and the regression model in @sec-model.


@fig-scatterplot displays the relationship between these two variables in a scatterplot.


@tbl-stats displays basic summary statistics for these two variables.


We can fit a simple linear regression model of the form shown in @eq-slr.

이 예시는 섹션, 그림, 수식을 상호 참조하는 방법을 포함합니다. 아래 표는 각 항목을 어떻게 표현하는지 요약합니다.

항목	참조	레이블 / 캡션
섹션	`@sec-eda`	제목에 추가한 ID: `# Exploratory data analysis {#sec-eda}`
그림	`@fig-scatterplot`	코드 셀의 YAML 옵션: `#\| label: fig-scatterplot #\| fig-cap: "Scatterplot of price vs. area of houses in Duke Forest"`
표	`@tbl-stats`	코드 셀의 YAML 옵션: `#\| label: tbl-stats #\| tbl-cap: "Summary statistics for price and area of houses in Duke Forest"`
수식	`@eq-slr`	표시 수식의 끝에 추가: `$$ {#eq-slr}`

자세한 내용과 캡션/참조 텍스트 사용자화(예: “Figure” 대신 “Fig.” 사용) 방법은 상호 참조 문서를 참고하세요.

콜아웃

콜아웃은 특정 개념에 특별히 주의를 끌거나, 특정 상황에서만 적용되는 보조 내용을 더 명확히 표시하는 좋은 방법입니다.

콜아웃은 특별한 속성을 가진 마크다운 div입니다. Insert Anything 도구를 사용해 콜아웃을 삽입할 수 있습니다.

Insert Anything 도구로 콜아웃을 삽입하는 모습.

다음 대화 상자에서 다섯 가지 콜아웃 유형(note, tip, important, caution, warning) 중 하나를 선택하고, 모양(기본, 단순, 최소)을 사용자화하며, 아이콘 표시 여부를 결정할 수 있습니다.

콜아웃 대화 상자. note 유형이 선택되어 있고 기본 모양이며 아이콘 표시가 체크되어 있습니다.

그런 다음 콜아웃 상자에 다음 텍스트를 삽입해 보세요.

This is a pretty incomplete analysis, but hopefully the document provides a good overview of some of the authoring features of Quarto!

다음은 시각적 편집기에서 보이는 콜아웃 모습입니다.

시각적 편집기의 콜아웃 상자. 콜아웃 텍스트는 "This is a pretty incomplete analysis, but hopefully the document provides a good overview of some of the authoring features of Quarto!"입니다.

다음은 출력 문서에서 렌더링된 콜아웃입니다.

렌더링된 HTML 문서의 콜아웃 상자. 콜아웃 텍스트는 "This is a pretty incomplete analysis, but hopefully the document provides a good overview of some of the authoring features of Quarto!"입니다.

콜아웃 유형과 모양 옵션에 대해서는 콜아웃 문서를 참고하세요.

문서 레이아웃

Quarto 문서 본문의 기본 너비는 약 700픽셀입니다. 이 너비는 가독성 최적화를 고려하여 선택되었습니다. 보통 문서 여백에 여유 공간이 남으며, 이를 활용하는 방법이 몇 가지 있습니다.

column: page-right 셀 옵션을 사용하면 그림이 화면 전체 너비를 차지하되 약간의 인셋을 두도록 할 수 있습니다. fig-histogram 레이블이 있는 청크에 이 옵션을 추가해 보세요.

#| label: fig-histogram
#| fig-cap: "Histograms of individual variables"
#| fig-subcap:
#|   - "Histogram of `price`s"
#|   - "Histogram of `area`s" 
#| layout-ncol: 2
#| column: page-right

관련 섹션이 렌더링되면 다음과 같이 보입니다.

authoring.qmd를 HTML로 렌더링한 결과. 탐색적 데이터 분석 섹션에서 나란히 배치된 히스토그램이 문서 본문보다 넓게 표시됩니다.

여백에는 인용, 각주, 보조 설명을 배치할 수 있습니다. 그림, 표, 기타 콘텐츠에 대해 사용자 정의 열 너비를 지정할 수도 있습니다. 자세한 내용은 문서 레이아웃 문서를 참고하세요.

배포

문서를 HTML로 렌더링한 뒤에는 편집기 도구 모음 또는 미리보기 창에서 Publish 버튼을 클릭하는 것만으로 RPubs(RStudio에서 제공하는 무료 웹 공유 서비스)에 배포할 수 있습니다. 또는 quarto::quarto_publish_doc() 함수를 사용할 수 있습니다.

quarto::quarto_publish_doc(
  "authoring.qmd", 
  server = "rpubs.com"
  )

다른 배포 옵션으로는 RStudio Connect와 ShinyApps, GitHub Pages, Netlify 등이 있습니다. 배포 옵션에 대한 자세한 개요는 Publishing HTML 문서를 참고하세요.

이 튜토리얼을 단계별로 따라 했다면, 이제 우리가 다룬 모든 내용을 구현한 Quarto 문서를 갖게 되었을 것입니다. 그렇지 않다면 아래에서 computations.qmd의 완료 버전을 다운로드할 수 있습니다.

Download authoring-complete.qmd

더 알아보기

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

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