quarto R 패키지 v1.5.0: R 사용자를 위한 간소화된 워크플로

quarto R 패키지 1.5.0이 출시되었습니다! 이번 릴리스는 R 사용자의 워크플로를 크게 개선하여 Quarto를 더욱 유연하고 강력하게 만드는 데 집중합니다.

새 기능

CRAN에서 최신 버전을 설치하세요:

install.packages("quarto")

• 이번 릴리스의 주요 기능은 다음과 같습니다:

• Quarto 메타데이터에 R 값 전달하기 - knitr 엔진으로 계산한 값을 기반으로 메타데이터를 프로그래밍 방식으로 설정

• Quarto 처리용 HTML 테이블에 Markdown 삽입 - 수식, 링크, 서식 등 Markdown 내용을 HTML 테이블에 포함

• 플롯과 테이블에 라이트 및 다크 테마 적용 - 라이트/다크 테마에 따라 플롯과 테이블의 배경 및 전경색을 변경

• R 스크립트와 Quarto 함께 사용 - Quarto 문서에서 R 코드를 추출하거나 Quarto 렌더링용 R 스크립트를 준비

• Quarto 프로젝트에서 경로 만들기 - R 셀에서 Quarto 프로젝트 루트를 기준으로 경로를 구성

• R에서 Quarto CLI 자동화 - Quarto CLI 기능을 감싸는 새로운 개선된 래퍼로 자동화를 더 쉽게

Quarto 메타데이터에 R 값 전달하기

write_yaml_metadata_block()를 사용하여 R 계산 결과에 따라 메타데이터를 동적으로 설정할 수 있습니다. 예를 들어 매개변수 값을 확인하고, 그에 따라 콘텐츠를 조건부로 포함할 수 있습니다:

#| output: asis

write_yaml_metadata_block(
  is_france = params$country == "france"
)

이 코드는 다음과 같은 YAML을 작성합니다(예: quarto render report.qmd -P country:france 실행 시):

---
is_france: true
---

그런 다음 Quarto의 조건부 기능을 사용하세요:

::: {.content-visible when-meta="is_france"}
## 프랑스에 대한 흥미로운 사실

2025년 프랑스는 연간 8,900만 명이 넘는 관광객을 끌어들이며 세계에서 가장 많이 방문받는 나라입니다!

:::

YAML 1.2 호환성 개선

이 함수는 YAML 따옴표의 특수한 예외 상황을 올바르게 처리합니다. 특히 YAML 1.1에서 지원하지 않는 8진수처럼 보이는 문자열(예: "0888" 또는 "0999")을 자동으로 따옴표 처리합니다:

# These octal-like values are automatically quoted to prevent errors
write_yaml_metadata_block(
  code1 = "0888",    # Without quoting: YAML 1.2 interprets as 888 (invalid octal ignored)
  code2 = "0999"     # Without quoting: YAML 1.2 interprets as 999 (invalid octal ignored)
)

자동 따옴표 처리 없이 이러한 값은 YAML 1.2에서 십진수(888 및 999)로 해석되어 앞자리 0이 사라집니다. 파일 권한이나 앞자리 0을 유지해야 하는 ID 코드처럼 문자열 값이 필요한 코드가 정상 작동하지 않을 수 있습니다.

이 변경은 R 객체 목록에서 YAML을 작성하는 내부 함수에 적용되며, 특히 이러한 예외에 해당하는 파라미터 값이 포함될 수 있는 quarto_render()의 execute_params를 사용할 때 매우 중요합니다:

# Parameters with octal-like codes are now handled correctly
quarto_render("report.qmd", 
  execute_params = list(
    site_code = "0888",
    permission = "0755"
  ))

인용을 명시적으로 제어하려면 yaml_quote_string()을 사용하세요:

# Force specific values to be quoted in YAML output
metadata <- list(
  code1 = yaml_quote_string("1.0")
)
write_yaml_metadata_block(.list = metadata)

이렇게 하면 문자열이 YAML에서 이중 따옴표로 표시되어 제공한 문자 표현을 그대로 유지합니다.

dynamic metadata vignette에서 조건부 콘텐츠를 위해 매개변수를 메타데이터로 제공하는 방법을 포함하여 더 많은 예시를 확인할 수 있습니다.

Quarto 처리용 HTML 테이블에 Markdown 삽입

Quarto는 HTML 테이블에서 Markdown 콘텐츠를 파싱할 수 있어 수식, 링크, 텍스트 스타일 등 풍부한 형식을 지원합니다. 새로운 tbl_qmd_*() 함수는 이 강력한 Quarto 기능을 R에서 더 쉽게 사용할 수 있게 해줍니다:

data.frame(
  Feature = c("Formatting", "Math", "Links"),
  Example = c(
    tbl_qmd_span("**Bold**, *italic*"),
    tbl_qmd_span("$E = mc^2$"),
    tbl_qmd_span("[Quarto docs](https://quarto.org)")
  )
) |>
  knitr::kable(format = "html", escape = FALSE)

이 헬퍼 함수는 Quarto가 Markdown 처리를 인식하는 data-qmd-base64 속성을 가진 HTML span으로 콘텐츠를 감싸며, raw HTML을 지원하는 모든 테이블 패키지(knitr, kableExtra, DT)에서 작동합니다. Quarto에서만 작동하는 콘텐츠는 display 인수를 사용해 우아하게 대체하세요. Markdown in HTML tables vignette에서 다양한 패키지의 HTML 테이블에 대한 Markdown 지원을 비교한 예시를 포함하여 더 많은 예제를 확인할 수 있습니다.

플롯과 테이블에 라이트 및 다크 테마 적용

theme_colors_flextable(), theme_colors_ggplot2(), theme_colors_gt(), theme_colors_plotly(), theme_colors_thematic() 헬퍼 함수는 여섯 가지 인기 플롯 및 테이블 패키지의 배경과 전경색을 변경합니다. 이들은 라이트/다크 모드 테마에 맞춰 플롯이나 테이블을 라이트 및 다크 렌더링으로 출력하는 데 사용할 수 있습니다.

이 함수들의 결과 활용법은 패키지마다 다릅니다. theme_colors_*의 사용 예시는 Theme Helpers 문서를 참고하세요.

theme_brand_flextable(), theme_brand_ggplot2(), theme_brand_gt(), theme_brand_plotly(), theme_brand_thematic() 헬퍼 함수는 대응되는 brand.yml 색상을 사용해 이러한 패키지의 배경과 전경색을 변경합니다. theme_brand_*의 사용 예시는 Light & Dark Renderings Examples에서 확인할 수 있습니다.

R 스크립트와 Quarto 함께 사용하기

Quarto 문서에서 R 코드 추출

새로운 qmd_to_r_script() 함수는 quarto inspect를 활용하여 코드 추출을 수행하는 knitr::purl()의 대안입니다:

# Extract R code from a Quarto document
qmd_to_r_script("analysis.qmd")  # Creates "analysis.R"

# Specify custom output
qmd_to_r_script("analysis.qmd", script = "extracted-code.R")

이 함수는 R 실행 대신 Quarto의 정적 문서 분석을 활용하므로 간단한 코드 추출을 더 빠르고 안전하게 수행합니다. 셀 옵션을 그대로 유지하고 eval: false로 표시된 셀을 주석 처리하며, purl: false로 지정된 콘텐츠를 무시합니다. child= 청크나 knitr::read_chunk() 같은 고급 knitr 기능을 사용하는 문서에서는 실제 문서 처리를 수행하는 knitr::purl()을 계속 권장합니다.

Quarto 렌더링을 위한 R 스크립트 준비

Quarto는 R 스크립트를 직접 렌더링할 수 있으며, 특별히 형식을 갖춘 주석을 Markdown으로 처리합니다. add_spin_preamble() 함수는 이 기능을 위해 필요한 YAML 메타데이터를 추가하여 R 스크립트를 준비합니다:

# Add metadata for rendering
add_spin_preamble("analysis.R", 
                  title = "Analysis Report",
                  preamble = list(author = "Data Team"))

# Now render the script with Quarto
quarto_render("analysis.R")

이 함수는 Quarto가 인식하는 최소한의 spin 스타일 프렐리머( #' 주석 사용)를 추가합니다:

#' ---
#' title: Analysis Report
#' author: Data Team
#' ---
#'

# Your original R code follows...

이 프렐리머는 Quarto의 engine binding이 스크립트를 올바르게 처리하도록 하며, .qmd 파일과 함께 R 스크립트를 원본 문서로 사용할 수 있게 합니다. R 스크립트 활용에 대해서는 R scripts vignette를 참고하세요.

Quarto 프로젝트에서 경로 만들기

Quarto는 렌더링 중에 프로젝트 루트를 식별하는 환경 변수를 설정하지만, knitr는 기본적으로 이 정보를 직접 참조할 수 없습니다. 새로운 프로젝트 탐색 함수는 이 간극을 메웁니다:

# Build paths relative to the Quarto project root
data_file <- project_path("data", "analysis.csv")

# Explicitly find the project root (searches for _quarto.yml)
root <- find_project_root()

project_path() 는 다양한 실행 컨텍스트를 지능적으로 처리합니다:

• quarto render 실행 시에는 QUARTO_PROJECT_ROOT 또는 QUARTO_PROJECT_DIR 환경 변수를 사용합니다.
• 대화형 세션에서는 _quarto.yml을 찾아 프로젝트 루트를 자동으로 감지합니다.
• 프로젝트를 찾을 수 없으면 현재 작업 디렉터리를 경고와 함께 사용합니다.

이 덕분에 경로를 하드코딩하거나 수동으로 조정하지 않고도 일관되게 작동시킬 수 있습니다. 예를 들어 프로젝트 루트를 기준으로 CSV 파일을 읽을 수 있습니다:

# In posts/2025/analysis/report.qmd, this resolves to ../../../data/results.csv
results <- read.csv(project_path("data", "results.csv"))

명시적 제어가 필요하다면 대안으로 here::i_am()과 here::here()를 고려하세요. 다음 버전의 here에서 추가 지원이 예정된 사항은 r-lib/usethis 이슈 #128를 참고하세요.

R에서 Quarto CLI 자동화

quarto R 패키지는 Quarto CLI를 포괄적으로 감싸 R 워크플로와 파이프라인에 자연스럽게 통합하는 방식으로 설계되었습니다. 이번 릴리스에서는 개선된 래퍼와 새로운 헬퍼로 그 기반을 더욱 강화합니다.

확장 관리

프로그래밍 방식으로 Quarto 확장을 관리하세요:

# Add an extension
quarto_add_extension("quarto-journals/jss")

# List installed extensions
quarto_list_extensions()

# Remove an extension
quarto_remove_extension("jss")

프로젝트 및 버전 관리

자주 사용하는 CLI 작업을 위한 새로운 헬퍼:

# Create projects from templates
quarto_create("article", name = "my-analysis")

# Check if a newer version of Quarto is available
check_newer_version()

문서 점검

quarto inspect 결과를 활용하여 문서에 대한 질문에 답하세요:

# Check if a document has parameters (uses quarto inspect internally)
if (has_parameters("report.qmd")) {
  quarto_render("report.qmd", execute_params = list(year = 2025))
}

이러한 CLI 래퍼는 R 내부에서 CI/CD 파이프라인, 배치 처리, 동적 프로젝트 관리 같은 자동화 시나리오를 구현할 수 있게 해줍니다. 일관된 인터페이스 덕분에 R 환경을 벗어나지 않고도 복잡한 Quarto 워크플로를 스크립팅할 수 있습니다.

추가 개선 사항

blogdown 사용자를 위한 익숙한 워크플로

new_blog_post() 함수는 blogdown에서 전환하는 사용자에게 익숙한 워크플로를 제공합니다:

# Create a new blog post with automatic date prefix and YAML frontmatter
new_blog_post("my-first-quarto-post", dir = "posts")

blogdown의 new_post()처럼 이 함수는 Quarto 블로그에 적절한 디렉터리 구조와 올바른 YAML frontmatter를 갖춘 새 블로그 포스트 파일을 자동으로 생성하여 blogdown에서 Quarto로의 전환을 더 부드럽게 만듭니다.

bookdown 프로젝트를 위한 마이그레이션 헬퍼

detect_bookdown_crossrefs() 함수는 변환이 필요한 bookdown 상호 참조 구문을 식별하는 데 도움을 줍니다:

# Scan your bookdown project for cross-references
detect_bookdown_crossrefs("my-bookdown-project/")

이 함수는 콘솔에 다음과 같은 상세 안내를 출력합니다:

• 어떤 상호 참조 패턴을 수동으로 변환해야 하는지
• 어떤 패턴을 자동으로 변환할 수 있는지
• 파일에서 나온 실제 예시

다음은 bookdown book 소스의 예시 출력입니다:

> detect_bookdown_crossrefs("~/Documents/DEV_R/bookdown/inst/examples", verbose = FALSE)
ℹ Scanning for bookdown cross-references in 12 .Rmd files...
! Found 110 bookdown cross-references that should be converted:

• 01-introduction.Rmd: 3 references
- 3 Sec

• 02-components.Rmd: 52 references
- 5 Eq
- 7 Fig
- 1 Lem
- 1 Lemma Div
- 7 Numbered Equation
- 17 Sec
- 5 Tab
- 5 Theorem Div
- 4 Thm

• 03-formats.Rmd: 20 references
- 4 Fig
- 16 Sec

• 04-customization.Rmd: 5 references
- 5 Sec

• 05-editing.Rmd: 8 references
- 3 Fig
- 5 Sec

• 06-publishing.Rmd: 8 references
- 3 Fig
- 5 Sec

• 08-usage.Rmd: 3 references
- 3 Sec

• index.Rmd: 11 references
- 11 Sec

ℹ Summary of conversion requirements:
• 5 Eq reference
• 17 Fig reference
• 1 Lem reference
• 1 Lemma Div reference
• 7 Numbered Equation reference
• 65 Sec reference
• 5 Tab reference
• 5 Theorem Div reference
• 4 Thm reference

ℹ Manual conversion requirements:
• Section headers: 65 references need manual attention
• Figure labels: 17 references need manual attention
• Table labels: 5 references need manual attention
• Equation structure: 7 references need manual attention
• Theorem blocks: 6 references need manual attention

ℹ For detailed conversion guidance, run: quarto::detect_bookdown_crossrefs("~/Documents/DEV_R/bookdown/inst/examples", verbose = TRUE)

중괄호 문법의 청크 헤더를 Quarto YAML 스타일로 변환할 때 knitr::convert_chunk_header()를 사용할 수 있다는 점을 기억하세요:

# Convert {r label, option=value} to YAML-style chunk options for a single file
knitr::convert_chunk_header("analysis.Rmd", output = NULL)

# To process multiple files in a directory, you need to iterate:
rmd_files <- list.files("my-bookdown-project/", pattern = "\\.Rmd$", 
                        full.names = TRUE, recursive = TRUE)
lapply(rmd_files, knitr::convert_chunk_header, output = NULL)

이 도구들을 함께 사용하면 bookdown에서 Quarto로 마이그레이션할 때 주요 구문 차이를 해결할 수 있습니다.

향상된 워크플로

• quarto_preview()는 자동화를 위해 미리보기 URL을 반환합니다.
• QUARTO_R_DEBUG=TRUE 환경 변수 덕분에 디버깅이 향상되었습니다.
• 임베디드 프로세스에서 R 버전 사용이 일관됩니다.

중대한 변경 사항

출력 파일 처리

quarto_render()의 output_file 매개변수는 이제 --output CLI 플래그를 Quarto에 전달하는 대신 output-file 메타데이터 필드를 설정합니다. 이 변경은 Quarto의 메타데이터 처리를 더 잘 따르며 여러 출력 형식을 지원할 수 있게 합니다:

# Sets output-file metadata (like having 'output-file: report.html' in YAML)
quarto_render("doc.qmd", output_file = "report.html")

기존 CLI 플래그 동작이 반드시 필요하다면 quarto_args를 사용하세요:

# Use CLI flag directly
quarto_render("doc.qmd", quarto_args = c("--output", "report.html"))

템플릿 사용

quarto_use_template()은 이제 빈 디렉터리를 요구하며, 비어 있지 않은 디렉터리에서 사용할 경우 명확한 오류 메시지와 함께 실패합니다:

# Create an empty directory first
dir.create("my-article")
quarto_use_template("quarto-journals/jss", dir = "my-article")

이 변경은 프로그래밍 방식 사용을 위한 대화형 프롬프트를 제거한 Quarto CLI 업데이트를 따른 것입니다. 기존 디렉터리에서 템플릿을 사용해야 한다면 터미널에서 quarto use template을 직접 실행하여 대화형 설치를 수행하세요.

더 알아보기

새로운 기능과 개선 사항을 살펴보세요:

• R 패키지 문서: https://quarto-dev.github.io/quarto-r/
• 전체 변경 로그: https://quarto-dev.github.io/quarto-r/news/index.html
• 이슈 보고: https://github.com/quarto-dev/quarto-r/issues

자세한 예시와 워크플로는 다음 새 vignette에서 확인하세요:

• Dynamic metadata (동적 메타데이터)
• Markdown in HTML tables (HTML 테이블의 Markdown)
• Working with R scripts (R 스크립트 작업)
• All vignettes (모든 vignette)

감사의 말

이번 릴리스를 만든 데 기여해 주신 모든 분들께 특별히 감사드립니다:

@asadow, @caiolivf, @caocloud, @cderv, @coatless, @ColinFay, @cwickham, @davidrsch, @DillonHammill, @eitsupi, @GeorgeBatten, @gordonwoodhull, @jennybc, @jeroen, @joanbadia, @JosephBARBIERDARNAL, @LiNk-NY, @llrs-roche, @milanmlft, @papayoun, @petermacp, @remlapmot, @salim-b, @saudiwin, @smzimbo-bayer, @srvanderplas, and @wjschne.

---

R과 함께 즐거운 Quarto 작업 되세요!