프로젝트 기초

개요

Quarto 프로젝트는 다음을 제공하는 디렉터리입니다.

  • 단일 명령으로 디렉터리의 일부 또는 전체 파일을 렌더링하는 방법(예: quarto render myproject).

  • 여러 문서에서 YAML 구성을 공유하는 방법.

  • 출력 산출물을 다른 디렉터리로 리다이렉트하는 기능.

  • 렌더링된 출력을 동결하는 기능(즉, 문서가 변경되지 않으면 재실행하지 않음).

또한 프로젝트에는 추가 동작을 제공하는 특별한 “유형”이 있을 수 있습니다(예: 웹사이트 또는 책).

Note

Quarto를 이제 막 시작했거나 마크다운 퍼블리싱 시스템 경험이 없다면, 지금은 프로젝트 학습을 건너뛰는 것이 좋습니다. 기본에 익숙해지면 이 문서로 돌아와 더 알아보세요.

프로젝트 만들기

quarto create project 명령을 사용하면 프롬프트를 통해 새 프로젝트를 만들 수 있습니다.

Terminal
quarto create project
Output
 ? Type
 ❯ default
   website
   blog
   manuscript
   book
   confluence

또는 유형과 프로젝트 이름을 인자로 지정할 수 있습니다.

Terminal
quarto create project <type> <name>

공유 메타데이터

Quarto 프로젝트의 가장 중요한 기능 중 하나는 여러 문서에서 YAML 메타데이터 옵션을 공유할 수 있다는 점입니다. 공유 메타데이터는 프로젝트 수준과 디렉터리 수준 모두에 정의할 수 있습니다.

프로젝트 메타데이터

모든 Quarto 프로젝트에는 _quarto.yml 구성 파일이 포함됩니다. 프로젝트 디렉터리 안에서 렌더링되는 모든 문서는 프로젝트 수준에 정의된 메타데이터를 자동으로 상속합니다. 다음은 _quarto.yml 파일의 예시입니다.

_quarto.yml
project:
  output-dir: _output

toc: true
number-sections: true
bibliography: references.bib  
  
format:
  html:
    css: styles.css
    html-math-method: katex
  pdf:
    documentclass: report
    margin-left: 30mm
    margin-right: 30mm

프로젝트 파일에는 모든 형식에 적용되는 전역 옵션(예: toc, bibliography)과 형식별 옵션이 모두 포함됩니다.

프로젝트 프로필에 따라(예: 개발/운영, 책/웹사이트의 여러 버전) 프로젝트 메타데이터를 더 세분화해 사용자 지정할 수 있습니다. 자세한 내용은 프로젝트 프로필 문서를 참고하세요.

디렉터리 메타데이터

디렉터리 안의 파일에만 상속되는 메타데이터를 정의할 수도 있습니다. 이를 위해 메타데이터를 공유할 디렉터리에 _metadata.yml 파일을 추가하세요. 예를 들어 다음 _metadata.yml은 프레젠테이션 시리즈의 기본 Revealjs 옵션을 설정하고 해당 디렉터리 문서의 search를 비활성화합니다.

_metadata.yml
format:
  revealjs: 
    menu: false
    progress: false
search: false

이 파일의 옵션은 _quarto.yml과 동일한 스키마를 사용하며, _quarto.yml에 이미 제공된 옵션과 병합됩니다.

메타데이터 병합

_quarto.yml, _metadata.yml, 문서 수준 YAML 옵션에 정의된 메타데이터는 함께 병합됩니다. 우선순위는 문서 수준 옵션, 디렉터리 옵션, 프로젝트 수준 옵션 순입니다.

File Role
_quarto.yml Project level default options
dir/_metadata.yml Directory level default options (overrides project)
dir/document.qmd Document options (overrides directory and project)

메타데이터를 결합할 때는 객체와 배열이 단순히 덮어쓰기 되는 것이 아니라 병합됩니다. 예를 들어 출력 형식과 참고문헌에 영향을 주는 프로젝트/디렉터리 수준 옵션은 다음과 같이 병합됩니다.

_quarto.yml
format:
  html:
    toc: true
bibliography:
  - refs.bib

dir/_metadata.yml
format:
  html:
    code-fold: true
bibliography:
  - proj.bib

merged
format:
  html:
    toc: true
    code-fold: true
bibliography:
  - refs.bib
  - proj.bib

메타데이터 병합의 예외는 format입니다. 문서 수준 YAML에 형식을 정의하면 렌더링할 형식의 전체 목록을 반드시 정의해야 합니다.

메타데이터 포함

메타데이터를 여러 파일로 분리하면 더 편리할 수 있습니다. 이때 metadata-files 옵션을 사용합니다. 예를 들어 다음은 _quarto.yml에서 별도의 _website.yml로 웹사이트 옵션 일부를 포함합니다.

_quarto.yml
project:
  type: website
  
metadata-files:
  - _website.yml
_website.yml
website:
  navbar:
    background: primary
    left:
      - href: index.qmd
        text: Home
      - about.qmd

metadata-files에 나열된 파일은 프로젝트/디렉터리/문서 옵션과 동일한 방식으로 부모 파일과 병합됩니다. 즉, 포함된 파일은 새 옵션을 제공할 수도 있고 기존 옵션과 결합될 수도 있습니다.

로컬 구성

가끔은 버전 관리에 포함되지 않는 로컬 프로젝트 설정 변경을 정의하는 것이 유용합니다. 이를 위해 _quarto.yml.local 구성 파일을 만들 수 있습니다. 예를 들어 다음은 로컬 실행 시 실행 캐시를 사용하도록 지정합니다.

_quarto.yml.local
execute:
  cache: true

Quarto는 .local 파일이 커밋되지 않도록 .gitignore에 자동으로 항목을 추가합니다(참고로 환경 변수도 유사한 .local 파일에 정의할 수 있습니다).

프로젝트 렌더링

프로젝트 안의 파일을 하나씩 또는 한 번에 모두 렌더링할 수 있습니다(어느 경우든 공유 프로젝트 메타데이터가 사용됨).

프로젝트의 모든 문서를 렌더링하려면 프로젝트 디렉터리에서 quarto render를 사용하세요(또는 명령줄 인자로 특정 디렉터리를 지정할 수 있습니다).

Terminal
# render project in current dir
quarto render 

# render project in 'myproject'
quarto render myproject

프로젝트의 하위 디렉터리 안의 파일만 렌더링할 수도 있습니다. 예를 들어 현재 디렉터리에 tutorials, how-to, articles 하위 디렉터리가 있는 프로젝트가 있다면 articles의 내용만 다음과 같이 렌더링할 수 있습니다.

Terminal
# render only documents in the 'articles' sub-directory
quarto render articles

프로젝트를 렌더링할 때 quarto render에 전달한 명령줄 인자는 프로젝트의 각 파일에 적용됩니다. 예를 들어 다음 명령은 PDF 형식만 렌더링합니다.

Terminal
quarto render --to pdf
quarto render myproject --to pdf

R에서 Quarto를 사용 중이라면 quarto R 패키지로 R 콘솔에서 프로젝트를 렌더링할 수 있습니다.

library(quarto)
quarto_render()

렌더링 대상

기본적으로 프로젝트 디렉터리 안의 모든 유효한 Quarto 입력 파일(.qmd, .ipynb, .md, .Rmd)이 렌더링됩니다. 단, 다음에 해당하는 파일은 제외됩니다.

  1. 파일 또는 디렉터리 접두사가 .인 경우(숨김 파일)

  2. 파일 또는 디렉터리 접두사가 _인 경우(보통 최상위 파일이 아닌 경우, 예: 다른 파일에 포함되는 파일)

  3. README.md 또는 README.qmd 파일(대개 실제 렌더링 대상이 아니라 버전 관리 웹 UI에서 소스 코드를 볼 때의 안내용 콘텐츠)

프로젝트의 모든 대상 문서를 렌더링하고 싶지 않거나 렌더링 순서를 더 정확히 제어하고 싶다면 프로젝트 메타데이터에 project: render: [files] 항목을 추가할 수 있습니다. 예:

project:
  render:
    - section1.qmd
    - section2.qmd

render 목록을 정의할 때 와일드카드를 사용할 수 있습니다. 예:

project:
  render:
    - section*.qmd

render 목록에서 파일이나 디렉터리를 제외하려면 ! 접두사를 사용할 수 있습니다. 이 경우 렌더링하고 싶은 항목을 먼저 모두 지정해야 합니다. 예:

project:
  render:
    - "*.qmd"
    - "!ignored.qmd"
    - "!ignored-dir/"
Note

출력 파일 이름이 . 또는 _로 시작해야 하는 경우(예: Hugo 사용자의 _index.md)에는 Quarto 입력 파일 이름에서 접두사를 빼고(예: index.qmd), YAML에 output-file 매개변수를 명시적으로 추가해야 합니다. 예:

---
output-file: _index.md
---

엔진 우선순위

Quarto는 코드 실행을 위한 여러 엔진을 지원합니다. 과거에는 R, Python, Julia가 각각 하나의 엔진만 지원했기 때문에 실행 엔진을 선택할 필요가 없었습니다. 네이티브 Julia 엔진이 추가되면서 상황이 바뀌었습니다.

특정 노트북에서 사용할 실행 엔진을 결정할 때 Quarto는 미리 정의된 순서로 사용 가능한 엔진을 확인하므로, Julia의 경우 네이티브 엔진보다 Jupyter 엔진이 항상 우선됩니다.

Quarto 1.7부터는 프로젝트 내 모든 노트북의 프론트매터에 engine: julia를 지정하는 대신, 프로젝트 파일에서 engines 키로 다른 우선순위 순서를 설정할 수 있습니다.

여기에 나열한 엔진이 먼저, 지정한 순서대로 확인됩니다. 나머지 엔진은 Quarto의 기본 순서로 확인됩니다. 따라서 프로젝트 전체에서 네이티브 Julia 엔진을 사용하려면 프로젝트 파일에 다음 한 줄을 추가하면 됩니다.

_quarto.yml
engines: ['julia']

더 알아보기

다음 문서에서 Quarto 프로젝트의 고급 기능을 더 알아볼 수 있습니다.

  • 실행 관리: 계산 비용이 큰 사이트를 다시 빌드하는 데 걸리는 시간을 최소화하는 다양한 기법을 다룹니다.

  • 프로젝트 프로필: 다양한 상황(예: 개발/운영, 책/웹사이트의 여러 버전)에 맞게 옵션과 콘텐츠를 조정하는 방법을 설명합니다.

  • 환경 변수: 프로젝트 렌더링 시 항상 설정해야 하는 환경 변수를 정의하는 방법(프로젝트 프로필별 변형 및 로컬 개발용 설정 포함)을 다룹니다.

  • 프로젝트 스크립트: 입력 데이터와 프로젝트 출력에 대한 특별 처리용 주기적 또는 렌더링 전/후 스크립트를 추가하는 방법을 설명합니다.

  • 가상 환경: 프로젝트별 패키지 라이브러리를 만들어 시간이 지나도 환경을 충실히 재현하고, 한 프로젝트의 패키지 업그레이드가 다른 프로젝트를 깨뜨리지 않도록 하는 방법을 다룹니다.