프로젝트 유형

개요

커스텀 프로젝트 유형은 특정 목적에 맞게 프로젝트를 구성할 수 있게 해줍니다. 예를 들어 문서 작성이나 분석 수행을 위한 조직 차원의 표준을 구현하는 프로젝트 유형을 만들 수 있습니다.

예를 들어 lexdocs라는 프로젝트 유형 확장을 만들었다면 다음과 같이 사용할 수 있습니다:

_quarto.yml

project:
  type: lexdocs

이 한 줄의 설정으로 다음을 제공할 수 있습니다:

내비게이션 요소
헤더와 푸터
문서 필터
그래픽 요소
HTML 옵션 및 스타일

프로젝트 유형을 사용하는 스타터 템플릿으로 기본 골격을 함께 포함하고 GitHub 저장소에 호스팅하면, 사용자는 다음처럼 간단히 새 프로젝트를 시작할 수 있습니다:

Terminal

quarto use template lexcorp/lexdocs

위에서 설명한 GitHub 저장소 대신, 단순 gzip 아카이브로 프로젝트 유형 확장을 묶어 배포하는 것도 가능합니다. 자세한 내용은 확장 배포 문서를 참고하세요.

개발 도구

VS Code, Positron, RStudio에서 커스텀 프로젝트 유형을 사용한다면 최신 버전에서만 올바르게 동작합니다:

Quarto VS Code 확장은 1.45 이상을 사용하세요.
RStudio는 2022.12 이상을 사용하세요.

진행하기 전에 해당 도구의 버전을 업데이트하세요.

전체 예시

이 절에서는 앞서 언급한 lexdocs 프로젝트 유형의 전체 예시를 통해 프로젝트 유형 확장에 무엇이 포함되어야 하는지 설명합니다. lexdocs 프로젝트 유형에 포함된 파일은 다음과 같습니다:

_quarto.yml
index.qmd
team.qmd
_extensions
  lexdocs/
    _extension.yml
    lexcorp.png
    theme.scss
    filter.lua

이 저장소는 다음 두 가지를 모두 제공합니다:

프로젝트 유형 확장(_extensions 디렉터리).
프로젝트 유형용 스타터 템플릿(저장소 루트의 _quarto.yml, index.qmd, team.qmd).

프로젝트 유형 확장

먼저 확장 코드부터 살펴보겠습니다. 아래는 주요 _extension.yml 파일입니다:

_extensions/lexdocs/_extension.yml

title: Lexdocs Project
author: Lexcorp, Inc.
version: 1.0.0
quarto-required: ">=1.2.0"
contributes:
  project:
    project:
      type: website
    website:
      sidebar: 
        contents: auto
        search: true
        style: docked
        background: light
        logo: lexcorp.png
      page-footer: |
        "Copyright 2022, Lexcorp, Inc." 
    format: lexdocs-html
  formats:
    html:
      theme: [default, theme.scss]
      code-overflow: wrap
      code-line-numbers: true
      filters:
        - filter.lua

contributes 키에는 project 항목이 포함되며, 이 항목은 해당 프로젝트 유형을 사용할 때 _quarto.yml 설정 파일의 기본값을 정의합니다.

커스텀 프로젝트 유형은 Quarto 내장 기본 유형(default, website, book) 중 하나를 반드시 상속해야 합니다. 여기서는 project: type: website를 지정합니다.

또한 확장 안에 lexdocs-html 커스텀 포맷을 정의하고 이를 프로젝트의 기본 포맷으로 설정했습니다. 이렇게 하면 문서에서 해당 포맷을 명시적으로 참조할 수 있습니다(예: pdf와 lexdocs-html 두 변형을 함께 렌더링하려는 경우).

_extension.yml의 커스텀 project 정의에는 추가로 세 개의 파일이 참조됩니다. 소스 코드는 생략하고 역할만 정리하면 다음과 같습니다:

lexcorp.png: sidebar에 추가되는 로고.
theme.scss: HTML 출력용 커스텀 테마.
filter.lua: 포맷에 필요한 추가 변환.

스타터 템플릿

이 저장소는 루트에 다음 파일을 포함해 스타터 템플릿도 제공합니다:

_quarto.yml: 프로젝트 설정 파일
index.qmd: 비어 있는 기본 홈 페이지
team.qmd: 기여한 팀원을 나열하도록 권장하는 페이지

_quarto.yml의 예시는 다음과 같습니다:

_quarto.yml

project:
  title: "Docs Site"
  type: lexdocs
  
format:
  lexdocs-html:
    toc: true

템플릿 사용자는 기본 title을 변경하고, 필요한 프로젝트/웹사이트/포맷 수준 옵션을 추가할 수 있습니다(이 옵션들은 확장이 제공하는 기본값과 병합됩니다).

마크다운 배포

Quarto로 다른 배포 시스템용 마크다운을 생성한다면, 프로젝트 유형 확장을 사용해 Quarto 출력 마크다운을 조정하고 해당 시스템의 네이티브 미리보기와 통합할 수 있습니다.

Quarto에는 Hugo와 Docusaurus 통합을 위한 내장 프로젝트 유형이 있습니다. 아래에서 해당 소스 코드를 확인할 수 있습니다:

hugo 프로젝트 유형
docusaurus 프로젝트 유형

Hugo 예시

다음은 Hugo 프로젝트 유형의 _extension.yml 파일입니다(마크다운 배포용 프로젝트 유형을 만들 때 보통 추가로 지정하는 옵션을 보여줍니다. 아래에서 설명합니다):

_extension.yml

title: Hugo
author: RStudio, PBC
organization: quarto
contributes:
  project:
    project:
      type: default
      detect:
        - ["config.toml", "content"]
        - ["config/_default/config.toml", "content"]
      render:
        - "**/*.qmd"
        - "**/*.ipynb"
      preview:
        serve:
          cmd: "hugo serve --port {port} --bind {host} --navigateToChanged"
          env: 
            HUGO_RELATIVEURLS: "true"
          ready: "Web Server is available at"
    format: hugo-md
  formats:
    md:
      variant: gfm+yaml_metadata_block+definition_lists
      prefer-html: true
      fig-format: retina
      fig-width: 8
      fig-height: 5
      wrap: preserve

Hugo용 프로젝트 옵션 중 처음 보는 항목을 중심으로 살펴보겠습니다:

project:
  type: default
  detect:
    - ["config.toml", "content"]
    - ["config/_default/config.toml", "content"]
  render:
    - "**/*.qmd"
    - "**/*.ipynb"
  preview:
    serve:
      cmd: "hugo serve --port {port} --bind {host} --navigateToChanged"
      env: 
        HUGO_RELATIVEURLS: "true"
      ready: "Web Server is available at"

detect 옵션은 하나 이상의 파일 존재 여부로 이 프로젝트 유형을 자동 감지합니다.

render 옵션은 Quarto가 렌더링할 파일을 지정합니다(기본적으로 .md도 렌더링하지만, 이는 Hugo의 .md 네이티브 렌더링과 충돌하므로 여기서는 제외합니다).

preview 옵션은 quarto preview가 Hugo의 네이티브 미리보기 서버를 실행하도록 합니다. cmd는 사용할 셸 명령을 지정하며 {port}와 {host}를 보간합니다. env는 환경 변수 값을 지정하고, ready는 미리보기 서버가 시작되어 요청을 처리할 준비가 되었음을 나타내는 문자열을 설정합니다.

마크다운 포맷

마크다운 배포 시스템용 프로젝트 유형을 만들 때는 출력할 마크다운 변형을 정의하는 커스텀 포맷이 필요합니다. Hugo의 경우 variant 옵션으로 마크다운 변형을 지정합니다:

formats:
  md:
    variant: gfm+yaml_metadata_block+definition_lists+smart

그 결과 Hugo가 태그/카테고리 등에 필요로 하는 YAML 메타데이터 블록이 포함된 GitHub Flavored Markdown이 생성되며, 정의 목록과 스마트 타이포그래피도 지원됩니다.

일부 시스템에서는 변형 선언만으로는 충분하지 않습니다. 예를 들어 Docusaurus의 경우 MDX, 콜아웃, 탭셋 같은 Docusaurus 전용 구성을 처리하는 Lua 필터도 함께 지정합니다:

formats:
  md:
    variant: +yaml_metadata_block+pipe_tables+tex_math_dollars+header_attributes-all_symbols_escapable
    filters:
      - docusaurus.lua

각 마크다운 배포 시스템의 프로젝트 유형은 고유한 변형을 가지며, 대상 시스템의 비표준 구성과 특이점을 처리하기 위해 필터가 필요한 경우가 많습니다.