프로젝트 프로필

개요

프로젝트 프로필을 사용하면 다양한 상황에 맞게 프로젝트의 옵션, 환경, 콘텐츠를 조정할 수 있습니다. 예를 들어:

  • 운영 서버에서 실행할 때는 다른 실행 동작이 필요할 수 있습니다. 예를 들어 로컬 렌더링에서는 freeze나 cache를 사용하지만 CI 서버에서는 항상 모든 코드를 실행하도록 할 수 있습니다.
  • 프로필에 따라 데이터베이스나 웹 서비스 접근 자격 증명을 다르게 제공할 수 있습니다.
  • 같은 소스 코드로 책의 여러 버전(예: 기본/고급)을 만들 수 있습니다.

프로젝트 프로필이 활성화되면 다음이 적용됩니다.

  1. 프로필별 config가 최상위 _quarto.yml과 병합됩니다.
  2. 프로필별 환경 변수가 적용됩니다.
  3. div는 when-profile 속성을 사용해 해당 프로필 전용 콘텐츠를 지정할 수 있습니다.
  4. QUARTO_PROFILE 환경 변수에 프로필 이름이 포함되어 다른 코드(예: Python 또는 R 코드)가 활성 프로필에 따라 동작을 조정할 수 있습니다.

예시

다음은 _quarto-production.yml의 production 구성으로 확장되는 _quarto.yml 예시입니다. 활성화되면 production 프로필이 기본 렌더링 실행 동작을 덮어씁니다(freeze 사용 비활성화).

_quarto.yml
project:
  type: website
  
execute: 
  freeze: true
_quarto-production.yml
execute:
  freeze: false

production 프로필이 활성화되면 해당 구성은 기본 프로젝트 구성에 병합됩니다(이 경우 동결된 계산 결과 사용이 비활성화됨).

다음은 advanced 프로필이 활성화될 때만 콘텐츠를 포함하도록 when-profile 속성을 사용하는 예시입니다.

::: {.content-visible when-profile="advanced"}
This content will only appear in the advanced version.
:::

다음 섹션에서는 프로필을 활성화하는 방법을 다루고, 이후 섹션에서 프로필의 다양한 기능을 더 자세히 설명합니다.

프로필 활성화

하나 이상의 프로필은 QUARTO_PROFILE 환경 변수 또는 --profile 명령줄 인자로 활성화할 수 있습니다.

다음은 QUARTO_PROFILE 환경 변수로 프로필을 활성화하는 예시입니다.

Terminal
export QUARTO_PROFILE=production
quarto render

다음은 Quarto 명령줄에서 --profile 인자를 전달해 프로필을 활성화하는 예시입니다.

Terminal
quarto render --profile production

--profile 명령줄 인자를 사용하면 환경에 정의된 QUARTO_PROFILE 값이 완전히 대체됩니다.

한 번에 여러 프로필을 활성화할 수도 있습니다. 예를 들어 다음은 production과 advanced 프로필을 모두 활성화합니다.

Terminal
quarto render --profile production,advanced

프로필 구성

프로필 이름이 포함된 추가 프로젝트 파일을 만들어 프로필별 구성을 정의합니다(예: advanced 프로필의 _quarto-advanced.yml). 다음은 활성 프로필에 따라 title과 output-dir를 사용자 지정하는 예시입니다.

_quarto.yml
project:
  title: "My Website"
  type: website
_quarto-advanced.yml
project:
  title: "My Website (Advanced)"
  output-dir: _site-advanced
Warningmetadata-files는 프로필에서 해석되지 않음

프로필 구성에서 metadata-files를 사용하는 대신, 메타데이터 파일 내용을 프로필 구성 파일에 직접 복사하세요.

여러 프로필이 동시에 활성화될 수 있다는 점이 중요합니다. 따라서 다음은 advanced와 production 프로필 모두에 따라 구성을 변경할 수 있습니다.

_quarto.yml
project:
  title: "My Website"
  type: website
  
execute:
  freeze: true
_quarto-advanced.yml
project:
  title: "My Website (Advanced)"
  output-dir: _site-advanced
_quarto-production.yml
execute:
  freeze: false

advanced와 production을 모두 지정하면 두 프로필이 각각 적용됩니다.

Terminal
# multiple profiles in environment
export QUARTO_PROFILE=advanced,production
quarto render

# multiple profiles on command line
quarto render --profile advanced,production

프로필 콘텐츠

프로젝트 내 콘텐츠를 특정 프로필이 활성화될 때만 포함하도록 지정할 수도 있습니다. 이를 위해 div 또는 span에 .content-visible 클래스와 when-profile 속성을 사용합니다. 예를 들어 다음 div는 advanced 프로필에서만 포함됩니다.

::: {.content-visible when-profile="advanced"}
This content will only appear in the advanced version.
:::

unless-profile 속성을 사용하면 특정 프로필에서 콘텐츠를 제외할 수 있습니다. 다음은 프로필이 advanced가 아닐 때만 콘텐츠를 포함합니다.

::: {.content-visible unless-profile="advanced"}
This content will appear in all versions save for advanced.
:::

위 예시는 .content-hidden으로 다시 쓰면 더 명확할 수 있습니다.

::: {.content-hidden when-profile="advanced"}
This content will be hidden in the advanced profile
:::

프로필 그룹

때로는 프로필 이름 집합이 상호 배타적 그룹을 이루며, 항상 최소 하나의 프로필이 활성화되도록 보장하고 싶을 수 있습니다. 예를 들어 다음은 basic과 advanced 프로필에 대해 서로 다른 장 목록을 정의하고, group 항목으로 이들이 하나의 그룹임을 나타냅니다.

_quarto.yml
project:
  type: book
  
book:
  title: "My Book"
  author: "Norah Jones"

profile:
  group: 
    - [basic, advanced]
_quarto-basic.yml
book:
  chapters:
    - intro.qmd
    - using.qmd
    - summary.qmd
_quarto-advanced.yml
book:
  chapters:
    - intro.qmd
    - using.qmd
    - advanced.qmd
    - summary.qmd

book의 기본 옵션에는 장 목록이 없습니다(서로 다른 목록을 프로필에 의존하기 때문). 따라서 프로젝트를 성공적으로 렌더링하려면 항상 프로필을 정의해야 하며, 이는 로컬 작성과 미리보기에서 불편할 수 있습니다.

group을 지정하면 프로필 중 하나가 반드시 정의되어야 하며, 다른 프로필이 없을 때는 목록의 첫 번째를 기본으로 사용하도록 지정합니다.

기본 프로필

프로필을 사용하는 Quarto 프로젝트를 작성할 때는 기본으로 렌더링할 프로필을 바꿔 다양한 변형을 시험하고 싶을 수 있습니다.

셸에서 환경 변수를 정의해 이를 수행할 수도 있지만, Positron, VS Code, RStudio의 통합 렌더링/미리보기 기능을 사용할 때는 그다지 편리하지 않습니다.

명시적인 QUARTO_PROFILE 또는 --profile CLI 인자가 없을 때 사용할 기본 프로필을 정의하려면 profile 키에 default 옵션을 추가하세요. 예를 들어 다음은 지정이 없으면 development가 활성 프로필이 되도록 합니다.

_quarto.yml
profile:
  default: development