확장 배포

개요

Quarto 확장은 하나 이상의 확장을 포함하는 _extensions 하위 디렉터리를 가진 디렉터리입니다. _extensions 위쪽의 파일들은 설치되지 않으므로 보통 README, LICENSE, 예제, 테스트 케이스 등을 포함합니다.

확장을 최종 사용자에게 배포하는 방법은 두 가지입니다:

  1. 공개 GitHub 저장소에 확장을 배포합니다.

  2. 확장을 .zip 또는 .tar.gz 아카이브로 묶습니다.

각 방법의 장단점은 아래에서 다룹니다. 먼저 확장의 기본 파일 구조와 구성 내용을 살펴보겠습니다.

확장 구성

Quarto 확장은 하나 이상의 확장 기여물을 포함하는 _extensions 폴더가 있는 디렉터리입니다. 일반적으로는 단일 확장을 배포하지만, 하나의 확장 디렉터리에 여러 숏코드/필터 또는 둘의 조합을 포함할 수도 있습니다.

다음은 my-filter 확장의 구성입니다:

README.md
LICENSE
example.qmd
_extensions/
  my-filter/
    _extension.yml
    my-filter.lua

엄밀히 필요한 것은 _extensions 디렉터리뿐입니다(그 위의 파일은 설치 시 무시되며 사용자 용도입니다). 그래도 README.md와 LICENSE 파일을 포함하는 것이 좋고, example.qmd는 확장 개발에 유용합니다.

_extension.yml

각 확장은 _extension.yml 파일로 정의되며, 여기에는 확장의 메타데이터와 사용 시 제공하는 항목이 포함됩니다. 예를 들어 필터 확장의 _extension.yml은 다음과 같습니다:

title: My Filter
author: Cooltools
version: 1.0.0
quarto-required: ">=1.2.0"
contributes:
  filters:
    - my-filter.lua

_extension.yml에 지정할 수 있는 필드는 다음과 같습니다:

title

확장의 이름

author

확장 작성자

version

이번 릴리스의 시맨틱 버전 번호. 확장을 설치/업데이트/릴리스할 때 이 버전 번호가 요약 정보로 표시됩니다.

quarto-required

이 확장을 실행하는 데 필요한 최소 Quarto 버전을 나타내는 시맨틱 버전 번호.

contributes

렌더링에 기여하는 항목. 허용되는 하위 키는 다음과 같습니다:

shortcodes

확장이 설치될 때 로드할 숏코드 파일 목록.

filters

문서/프로젝트 렌더링에 사용되는 필터 목록에 이 확장이 포함될 때 로드할 필터 목록. 목록의 순서는 유지됩니다.

formats

출력 포맷과 그 포맷에 연결된 메타데이터의 키-값 쌍.

Note

version 필드는 시맨틱 버전 규칙에 부합하는지 검사됩니다. 유효한 version 값 예시는 다음과 같습니다:

  • 1.0.0
  • 2.3.4-alpha
  • 1.2.3-beta+build567
  • 3.0.0-alpha.2
  • 4.2.1+build.987

유효하지 않은 version 값 예시는 다음과 같습니다:

  • 1.2 (missing patch version)
  • 1.2.3.4 (extra version segment)
  • 1.2.3-beta.5+build (missing build metadata identifier)

GitHub 배포

GitHub에 확장을 배포하면 간결한 구문(quarto add org-name/extension), 조직 네임스페이스를 통한 이름 충돌 관리, 특정 릴리스/태그 지정 등 여러 장점이 있습니다.

For example, the extensions in the quarto-ext GitHub organization can be added to a project with these commands:

Terminal
quarto add quarto-ext/lightbox
quarto add quarto-ext/fontawesome

기본적으로 확장은 저장소 main 브랜치의 HEAD에서 추가됩니다. 저장소 이름 뒤에 @를 붙이면 특정 태그/브랜치도 지정할 수 있습니다. 예:

Terminal
quarto add quarto-ext/lightbox@v1.2
quarto add quarto-ext/lightbox@bugfix-22

GitHub에서 추가된 확장은 조직 네임스페이스를 사용해 동일한 이름의 확장을 구분할 수 있습니다. 예를 들어 프로젝트에 lightbox 확장이 둘 있다면 quarto-ext를 다음과 같이 명시합니다:

---
filters:
  - quarto-ext/lightbox
---

GitHub 저장소의 하위 디렉터리에서 확장을 추가할 수도 있습니다. 예를 들어 cooltools/icons 저장소에서 두 확장을 설치할 수 있습니다:

Terminal
quarto add cooltools/icons/fontawesome
quarto add cooltools/icons/iconify

아카이브 배포

확장을 .zip 또는 .tar.gz 아카이브로 배포하면 공개 저장소 없이도 배포할 수 있습니다. 또한 GitHub이 아닌 버전 관리 서비스에서 제공하는 아카이브 URL로 직접 추가할 수 있습니다.

GitHub 호스팅 확장과 달리 아카이브로 설치한 확장은 조직 네임스페이스가 없습니다(모든 확장이 동일한 네임스페이스를 공유).

Git 저장소

GitLab 저장소에서 확장을 추가하려면 다음과 같이 할 수 있습니다:

Terminal
quarto add https://gitlab.com/cooltools/shorty/-/archive/main/shorty-main.zip

위 URL은 main 브랜치를 참조합니다. 다른 브랜치/태그/릴리스도 동일한 방식으로 지정할 수 있습니다. 예를 들어 v1.0 태그로 추가하려면:

Terminal
quarto add https://gitlab.com/cooltools/shorty/-/archive/v1.0/shorty-main.zip

BitBucket, Azure DevOps 등 다른 Git 호스팅 서비스를 사용한다면 해당 서비스 문서에서 아카이브 URL 생성 방법을 확인하세요.

아카이브 파일

위 예시는 Git 저장소에서 확장을 추가하는 방법입니다. 일반 웹 호스트에 배포된 아카이브에서도 확장을 추가할 수 있습니다. 예:

Terminal
quarto add https://cooltools.org/quarto/shorty.zip

또는 로컬 아카이브 파일이나 일반(압축되지 않은) 디렉터리에서도 추가할 수 있습니다:

Terminal
quarto add ~/Downloads/shorty.zip
quarto add /share/quarto/extensions/shorty