커스텀 포맷

개요

Quarto 포맷 확장을 사용하면 이미 제공되는 기본 포맷(예: html, pdf, docx)에 새로운 포맷을 추가할 수 있습니다. 커스텀 포맷은 기본 문서 옵션, 스타일시트, 헤더/푸터/로고 요소를 제공할 수 있고, 필터나 숏코드 같은 다른 확장을 함께 묶을 수도 있습니다. 조직 내 문서/프레젠테이션 작성의 공통 기준을 만들거나 특정 프로젝트/분석/출판에 맞는 기준을 제공하는 데 유용합니다.

커스텀 포맷은 기본 포맷과 동일하게 format 키 아래에 지정합니다. 예:

---
title: "My Document"
format:
   acm-pdf: 
     toc: true
---

모든 커스텀 포맷은 하나의 기본 포맷을 상속하며, 그 기본 포맷을 접미사로 포함합니다. 서로 다른 기본 포맷에서 파생된 여러 변형을 제공할 수도 있습니다. 예:

---
title: "My Document"
toc: true
format:
   acm-pdf: default
   acm-html: default
---

여기서는 toc 옵션이 두 포맷에 공통이므로 최상위로 옮겼습니다.

커스텀 포맷은 quarto render의 --to 인수로도 사용할 수 있습니다. 예:

Terminal
quarto render document.qmd --to acm-html

저널과 원고용 커스텀 포맷을 사용하거나 만들고자 한다면 저널 아티클 문서를 참고하세요.

빠른 시작

여기서는 간단한 HTML 기반 포맷 확장을 만드는 방법을 설명합니다. 이를 위해 quarto create 명령을 사용합니다. VS Code, Positron, RStudio를 사용 중이라면 각 통합 터미널에서 quarto create를 실행하세요.

시작하려면 포맷을 만들 상위 디렉터리에서 quarto create extension format:html을 실행합니다:

Terminal
$ quarto create extension format:html
 ? Extension Name › lexdoc

위와 같이 확장 이름을 묻게 됩니다. lexdoc(가상의 회사 LexCrop의 문서 포맷)를 입력하고 Enter를 누르면 커스텀 포맷 확장이 생성됩니다:

Creating extension at /Users/jjallaire/quarto/dev/lexdoc:
  - Created README.md
  - Created _extensions/lexdoc/custom.scss
  - Created _extensions/lexdoc/_extension.yml
  - Created template.qmd

VS Code, Positron, RStudio에서 실행 중이라면 새 창이 열리며 확장 프로젝트가 표시됩니다.

이 예시는 Quarto 기본 html 포맷을 파생한 포맷을 만듭니다. 같은 방식으로 pdf, docx, revealjs 파생 포맷도 만들 수 있습니다:

Terminal
quarto create extension format:pdf
quarto create extension format:docx
quarto create extension format:revealjs

_extensions/lexdoc/의 파일 구성은 다음과 같습니다:

_extensions/lexdoc/_extension.yml
title: Lexdoc
author: J.J. Allaire
version: 1.0.0
quarto-required: ">=1.2.222"
contributes:
  formats:
    html:
      toc: true
      theme: [yeti, custom.scss]

여기서 정의된 커스텀 HTML 포맷은 매우 단순합니다. 기본 html 포맷을 사용하고, 기본적으로 목차를 켜며, yeti 테마와 추가 커스터마이징을 위한 custom.scss를 설정합니다:

_extensions/lexdoc/custom.scss
/*-- scss:defaults --*/

/* TODO: Customize appearance with SCSS variables */
/* See [HTML theme](https://quarto.org/docs/output-formats/html-themes.html#theme-options) */

/*-- scss:rules --*/

/* TODO: Provide custom CSS rules */

마지막으로 template.qmd는 포맷 사용자에게 제공되는 기본 예제 문서입니다:

template.qmd
---
title: "Lexdoc Example"
format:
  lexdoc-html: default
author: J.J. Allaire
date: last-modified
---

## Introduction

*TODO* Create an example file that demonstrates the formatting and features of your format.

## More Information

You can learn more about controlling the appearance of HTML output here: <https://quarto.org/docs/output-formats/html-basics.html>

포맷을 개발하려면 template.qmd를 렌더/미리보기한 뒤 _extensions 디렉터리의 여러 파일을 수정하세요(파일이 변경되면 미리보기가 자동으로 갱신됩니다).

예제: Revealjs

다음으로 revealjs 프레젠테이션 포맷을 확장하는 커스텀 포맷을 만드는 과정을 살펴봅니다. 포맷 확장 저장소의 소스 코드는 다음과 같이 구성될 수 있습니다:

README.md
LICENSE
template.qmd
_extensions/
  lexconf/
    _extension.yml
    theme.scss
    logo.png
    title.png

포맷 접미사(revealjs)는 디렉터리 이름에서 제외합니다(예: lexconf-revealjs, lexconf-pptx 같은 다중 포맷을 대비).

다른 확장과 마찬가지로 엄밀히 필요한 것은 _extensions 디렉터리뿐입니다(그 위의 파일은 설치 시 무시됩니다). 그렇더라도 README.md와 LICENSE 파일을 포함하는 것이 좋습니다. template.qmd는 다음 목적을 갖습니다:

  1. 개발 중 포맷이 정상 동작하는지 렌더링으로 확인할 수 있습니다.
  2. 포맷 템플릿의 기반이 됩니다(사용자가 빠르게 시작하도록 도움).

_extension.yml 내용은 다음과 같습니다:

title: LexConf 2022 Presentation
author: LexCorp
version: 1.0.0
quarto-required: ">=1.2.0"
contributes:
  formats:
    revealjs:
       theme: [default, theme.scss]
       logo: logo.png
       footer: | 
         Copyright 2022 (c) LexCorp, Inc.
       title-slide-attributes:
          data-background-image: title.png
          data-background-size: contain
       preview-links: auto

이 포맷은 주로 조직 차원의 콘텐츠와 테마를 제공합니다. 앞서 언급했듯이, 포맷에는 커스텀 마크다운 구성과 렌더링 동작을 추가하기 위한 필터도 포함할 수 있습니다.

template.qmd의 내용 예시는 다음과 같습니다:

---
title: "Presentation"
subtitle: "LexConf 2022"
author: "Your Name"
date: today
format: lexconf-revealjs
---

# Overview

확장 저장소는 루트의 template.qmd를 바로 렌더링해 확장과 템플릿을 테스트할 수 있는 구조입니다. template.qmd는 설치 후와 동일하게 확장을 로드하므로, 확장 디렉터리 내에서 작업하면서 반복적으로 테스트할 수 있습니다(테스트를 위해 확장을 매번 설치/업데이트할 필요가 없습니다).

포맷 템플릿

앞서 확장과 함께 template.qmd를 포함하고 다음 명령으로 템플릿과 포맷을 함께 설치하는 방법을 설명했습니다:

Terminal
quarto use template <gh-organization>/<extension>

template.qmd는 포맷의 기능을 보여주고 사용자에게 좋은 출발점을 제공해야 합니다. 확장 템플릿이 대상 디렉터리로 복사될 때 template.qmd는 사용자가 지정한 디렉터리 이름에 맞게 자동으로 이름이 변경됩니다.

template.qmd와 함께 다른 파일을 포함하면 그 파일들도 복사됩니다. 기본적으로 Quarto는 확장 템플릿을 복사할 때 일반적인 GitHub 저장소 파일을 제외합니다. 여기에는 .로 시작하는 파일/디렉터리(예: .gitignore), README.md, LICENSE 등이 포함됩니다. 원한다면 저장소 루트에 .quartoignore 파일을 두고, 각 줄에 .gitignore와 같은 문법의 glob 패턴으로 제외할 파일을 지정할 수 있습니다.

형식 배포

형식 확장은 두 가지 방식으로 배포할 수 있습니다.

  1. _extensions 디렉터리에 형식과 template.qmd(둘러싼 디렉터리 이름과 일치하도록 자동 변경됨)를 함께 포함하는 템플릿

  2. 템플릿 스캐폴딩이 없는 순수 형식(기존 문서나 프로젝트에 형식을 추가할 때 유용)

위에서 lexconf 예시에 해당하는 파일이 있는 GitHub 저장소가 있다면, 사용자는 아래와 같이 확장과 템플릿을 설치할 수 있습니다(lexcorp는 저장소를 호스팅하는 GitHub 조직).

Terminal
quarto use template lexcorp/lexconf

이 방식은 바로 동작하는 문서를 제공하므로 형식을 시작하는 데 선호됩니다. 기존 프로젝트를 사용하는 경우 형식만 설치할 수도 있습니다.

Terminal
quarto add lexcorp/lexconf

확장은 GitHub 저장소 대신 단순 gzip 아카이브로도 묶어 배포할 수 있습니다. 자세한 내용은 확장 배포 문서를 참고하세요.

여러 형식

하나의 형식 확장이 여러 출력 형식을 지원할 수 있습니다. 예를 들어 확장이 html과 pdf 출력을 대상으로 할 수 있습니다. 여러 형식을 지원하려면 contributes / format 키에 기본 형식을 추가합니다.

contributes:
  format:
    html:
      # html-specific options
    pdf:
      # pdf-specific options

공통 메타데이터

형식 확장이 대상일 때 모든 출력 형식에 공통으로 적용될 메타데이터가 있다면 common 키 아래에 둘 수 있습니다. 예:

contributes:
  format:
    common:
      filters:
        - filter.lua
      shortcodes:
        - quarto-ext/fancy-text
    html:
      # html-specifc
    pdf:
      # pdf-specifc

형식 리소스

일반적으로 형식 확장 디렉터리 안에 다른 파일과 리소스를 두고, _extension.yml 메타데이터 파일에서 상대 경로로 참조하면 됩니다. 이러한 상대 경로는 확장의 메타데이터가 렌더링된 문서 메타데이터와 병합될 때 올바르게 처리됩니다.

문서 렌더링 과정에서 입력 디렉터리에 복사되어야 하는 리소스가 있다면(예: LaTeX 참고문헌의 bst 파일 또는 LaTeX 템플릿에서 참조되는 로고 파일 등), 파일 경로 목록인 format-resources를 제공할 수 있습니다1. 이 파일들은 문서가 렌더링될 때 렌더링 중인 입력이 있는 디렉터리로 복사됩니다. 예:

contributes:
  format:
    pdf:
      format-resources:
        - plos2015.bst

확장 임베딩

형식 확장에서 다른 확장을 사용하고 싶은 경우가 있습니다. 이는 가능하지만, 사용자 정의 형식 안에서 확장을 사용하려면 올바르게 임베딩되도록 특수 명령줄 플래그로 추가해야 합니다.

Terminal
quarto create extension format:pdf myformat
cd myformat
quarto add quarto-ext/fancy-text --embed myformat

예를 들어, fancy-text 확장(\(\LaTeX\)와 BibTEX 단어에 대한 특수 서식을 제공)를 jss 사용자 정의 형식 사용자에게 제공하려면 다음과 같이 합니다.

Terminal
quarto add quarto-ext/fancy-text --embed jss

그러면 다음과 같은 결과가 생성됩니다.

Output
quarto-journals/jss
└── _extensions
    └── jss
        ├── _extensions
        │   └── quarto-ext
        │       └── fancy-text
        └── partials

이렇게 하면 _extensions 폴더 안의 jss 확장에 quarto-ext/fancy-text 확장이 추가됩니다. 확장을 임베딩하면 사용자가 이미 설치한 다른 버전의 확장과 충돌할 가능성 없이 사용할 수 있습니다.

Footnotes

  1. 이는 Pandoc이 생성한 LaTeX를 PDF로 변환하는 추가 단계가 있는 PDF 기반 형식에서 가장 흔합니다. LaTeX가 간접적으로 참조하는 파일이 있다면 발견 가능해야 하며, 보통 LaTeX 입력이 있는 디렉터리로 복사해야 합니다.↩︎