`_brand.yml`로 여러 포맷에서 브랜딩하기

개요

Quarto는 여러 포맷의 문서 외관을 통일할 수 있는 단일 YAML 파일 brand.yml을 지원합니다. 다양한 포맷에서 일관된 스타일이 필요한 조직에 특히 유용합니다.

예시로 아래 _brand.yml 파일을 살펴보겠습니다.

_brand.yml

color:
  palette:
    dark-grey: "#222222"
    blue: "#ddeaf1"
  background: blue
  foreground: dark-grey
  primary: black

logo: 
  medium: logo.png

typography:
  fonts:
    - family: Jura
      source: google
  base: Jura
  headings: Jura

이 _brand.yml을 프로젝트에 추가하면 웹페이지, 프레젠테이션, PDF 보고서, 대시보드가 모두 동일한 외관을 공유합니다.

Webpage: html

Dashboard dashboard

Presentation: revealjs

PDF: typst

예제 보기: 소스 | 라이브 사이트

이 페이지에서 다루는 내용:

브랜드 파일 추가 방법
brand.yml 요소와 Quarto에서의 활용
brand.yml 밖에서 브랜드 값을 활용하는 방법
더 포괄적인 예시
_brand.yml 없이 만든 프로젝트를 마이그레이션하는 방법

제한 사항

brand.yml 스펙은 아직 개발 중이며 Quarto 지원도 완전하지 않습니다. 현재 지원되지 않는 부분은 이렇게 제한 사항 Callout으로 표시했습니다.

현재 brand.yml을 지원하는 포맷은 html, dashboard, revealjs, typst입니다.

브랜드 적용

프로젝트 루트( _quarto.yml과 같은 위치)에 _brand.yml 파일을 만들면 Quarto가 자동으로 감지해 지원 포맷 문서에 브랜드를 적용합니다.

Quarto 프로젝트 밖(예: _quarto.yml 없이)에서도 _brand.yml을 만들 수 있으며, 이 경우 동일 디렉터리에 있는 문서에 자동 적용됩니다.

_brand.yml

color:
  background: "#eeeeee"

문서별로 브랜드를 지정하려면 front matter에 brand 옵션을 추가해 값을 정의하세요.

document.qmd

---
brand:
  color:
    background: "#eeeeee"
---

문서 헤더에 brand를 지정하면 _brand.yml 설정 전체를 대체합니다.

특정 문서에서 브랜드를 사용하지 않으려면 brand: false로 설정하세요.

document.qmd

---
brand: false
---

_brand.yml을 하위 디렉터리에 두는 것도 가능합니다. 이때는 brand 키에 경로를 지정합니다. 예를 들어 brand/_brand.yml을 단일 문서에 적용하려면:

document.qmd

---
brand: brand/_brand.yml
---

프로젝트 전체 문서에 brand/_brand.yml을 적용하려면 _quarto.yml에 다음을 추가합니다.

_quarto.yml

brand: brand/_brand.yml

_brand.yml 내 경로는 브랜드 파일 위치를 기준으로 상대 경로입니다.

라이트/다크 색상

단일 brand.yml 파일에서 라이트/다크 모드 색상을 모두 지정하려면 color 혹은 typography 항목에 light, dark 값을 가진 객체를 사용하세요.

_brand.yml

color:
  background:
    light: "#ffffff"
    dark: "#333333"
  foreground:
    light: "#333333"
    dark: "#ffffff"
typography:
  headings:
    color:
      light: "#111144"
      dark: "#d0d0ff"

문서 front matter에 직접 브랜드를 정의하는 경우에도 동일하게 사용할 수 있습니다.

document.qmd

---
brand:
  color:
    background:
      light: "#ffffff"
      dark: "#333333"
    foreground:
      light: "#333333"
      dark: "#ffffff"
  typography:
    headings:
      color:
        light: "#111144"
        dark: "#d0d0ff"
---

제한 사항

palette 내 색상은 아직 light/dark 변형을 지원하지 않습니다.

라이트/다크 브랜드

색상이 아닌 속성까지 별도로 제어하고 싶거나 라이트/다크 브랜드를 각각 관리하고 싶다면 브랜드 파일을 분리하고 light, dark 경로를 지정할 수 있습니다.

document.qmd

---
brand:
  light: light-brand.yml
  dark: dark-brand.yml
---

이는 테마에서 라이트/다크 모드 지원 방식과 유사합니다.

문서 내부에서 브랜드를 정의하는 경우에도 사용할 수 있습니다.

document.qmd

---
brand:
  light:
    color:
      background: "#ffffff"
      foreground: "#333333"
  dark:
    color:
      background: "#333333"
      foreground: "#ffffff"
---

프로젝트 전역에서도 라이트/다크 브랜드 파일을 지정할 수 있습니다.

_quarto.yml

brand:
  light: light-brand.yml
  dark: dark-brand.yml

제한 사항

현재 _quarto.yml에 브랜드 메타데이터를 직접 선언할 수 없으며, 파일 경로를 통해서만 지정 가능합니다.

브랜드 모드

Typst와 revealjs 포맷은 라이트/다크 모드를 동적으로 전환할 수 없습니다.

기본적으로 라이트 브랜드가 사용되며, 다크 브랜드를 사용하려면 brand-mode: dark를 설정하세요.

Typst:

document.qmd

---
format:
  typst:
    brand-mode: dark
---

Revealjs:

document.qmd

---
format:
  revealjs:
    brand-mode: dark
---

브랜드 요소

brand.yml 구성 요소는 공식 문서에 정의되어 있습니다. 이 섹션에서는 Quarto에서 각 요소가 어떻게 사용되는지 살펴봅니다.

색상

색상 관련 문서

color 섹션에서는 브랜드 팔레트를 정의하고 이를 의미 색상(semantic color)에 매핑합니다. 예를 들어 연한 파란색을 background로 지정할 수 있습니다.

_brand.yml

color:
  background: "#ddeaf1"

palette 키를 사용하면 _brand.yml 내 다른 곳에서 참조할 수 있는 이름 있는 색을 정의합니다. 예를 들어 blue를 정의한 뒤 background로 지정할 수 있습니다.

_brand.yml

color:
  palette:
    blue: "#ddeaf1"
  background: blue

가장 자주 사용되는 의미 색상은 foreground, background, primary입니다.

_brand.yml

color:
  palette:
    dark-grey: "#222222"
    blue: "#ddeaf1"
  background: blue
  foreground: dark-grey
  primary: black

foreground와 background는 텍스트와 페이지 배경 색상을 지정하며 모든 포맷에서 동일하게 적용됩니다. primary는 링크, 네비게이션 바(html, dashboard), 진행 막대(revealjs) 등에 사용됩니다.

Bootstrap을 사용하는 HTML 포맷(html, dashboard)에서는 나머지 의미 색상이 동일 이름의 Bootstrap 변수에 매핑됩니다.

의미 색상 전체 목록

color에서 설정할 수 있는 의미 색상은 다음과 같습니다.

이름	설명
`foreground`	기본 텍스트 색상입니다. 보통 검정에 가깝고 배경색과의 대비가 높아야 합니다.
`background`	기본 배경색입니다. 보통 흰색에 가깝고 전경색과의 대비가 높아야 합니다.
`primary`	기본 강조 색상으로, 하이퍼링크, 활성 상태, 주요 동작 버튼에 사용됩니다.
`secondary`	보조 강조 색상으로, 밝은 텍스트나 비활성 상태에 자주 사용됩니다.
`tertiary`	3차 강조 색상으로, hover 상태, 강조 요소, wells에 사용됩니다.
`success`	긍정적이거나 성공적인 동작 및 정보를 나타내는 색상입니다.
`info`	중립적이거나 정보성 동작 및 정보를 나타내는 색상입니다.
`warning`	경고 또는 주의 동작 및 정보를 나타내는 색상입니다.
`danger`	오류, 위험 동작, 부정적 정보를 나타내는 색상입니다.
`light`	밝은 색상으로, 어두운 요소에서는 고대비 전경색으로, 밝은 요소에서는 저대비 배경색으로 사용됩니다.
`dark`	어두운 색상으로, 밝은 요소에서는 고대비 전경색으로, 밝은 요소에서는 고대비 배경색으로 사용됩니다.

SCSS나 brand 숏코드에서 이름 있는 색과 의미 색을 모두 참조할 수 있습니다. 자세한 내용은 _brand.yml 값 사용하기를 참고하세요.

로고

로고 관련 문서

logo 키로 브랜드 로고를 지정합니다.

_brand.yml

logo: 
  medium: logo.png

로고는 _brand.yml 기준 상대 경로 또는 URL로 지정할 수 있습니다.

하나의 로고만으로 모든 위치를 커버하기 어렵다면 small, medium, large 세 가지 크기를 지정할 수 있습니다.

_brand.yml

logo: 
  small: logo-small.png
  medium: logo.png
  large: logo-large.png

세 가지 모두를 지정할 필요는 없으며, Quarto가 아래 우선순위에 따라 사용합니다.

포맷 \| 위치 \| 우선순위 (높음→낮음)
`html`/`dashboard`	상단 내비게이션 바	`small`> `medium`>`large`
`html`	측면 내비게이션	`medium`>`small`>`large`
`typst`	좌측 상단, `format: typst: logo`로 제어	`medium`>`small`>`large`
`revealjs`	슬라이드 오른쪽 하단	`medium`>`small`>`large`
`website`/`book` project	브라우저 탭에 표시되는 `favicon`	`small`

images 아래에 로고를 이름으로 정의해 small, medium, large에서 참조할 수도 있습니다. 이 방법을 사용하면 alt 텍스트도 지정할 수 있습니다.

_brand.yml

logo: 
  images:
    quarto-logo: 
      path: https://quarto.org/quarto.png
      alt: "Quarto icon"
  small: quarto-logo

라이트/다크 로고

small, medium, large 항목 아래에 light, dark 옵션을 추가하면 라이트/다크 모드별로 다른 로고를 지정할 수 있습니다.

_brand.yml

logo:
  medium:
    light: logo.png
    dark: logo-white.png

문서 수준 로고 설정

문서 front matter의 logo 옵션으로 로고를 더 세밀하게 제어할 수 있습니다.

브랜드 로고 리소스를 직접 지정하거나,

document.qmd

---
logo: large
---

파일 경로를 지정해 이 문서에서만 다른 로고를 사용할 수도 있고,

document.qmd

---
logo: logo.png
---

브랜드 로고 리소스를 참조하면서 alt 텍스트만 변경할 수도 있습니다.

document.qmd

---
logo:
  path: large
  alt: Alternate alternate text
---

앞서 소개한 방식들을 조합해 라이트/다크 로고를 따로 지정하는 것도 가능합니다.

document.qmd

---
logo:
  light:
    path: large
    alt: Alternate alternate text
  dark:
    path: dark-logo.png
    alt: Alternate text for dark logo
---

제한 사항

현재는 웹사이트의 특정 페이지 로고만 다르게 설정할 수 없으며, 프로젝트 전역 _brand.yml만 적용됩니다. 관련 이슈: #11309

format: typst를 사용할 경우 로고 위치도 조정할 수 있습니다.

타이포그래피

타이포그래피 관련 문서

typography 요소는 글꼴과 스타일을 정의합니다. fonts 아래에 브랜드에서 사용할 글꼴 목록을 지정합니다.

_brand.yml

typography:
  fonts:
    - family: Jura
      source: google

fonts에서 설정 가능한 속성은 source에 따라 다릅니다. 사용 가능한 속성은 브랜드 메타데이터 문서를 참고하세요.

나머지 타이포그래피 옵션에서는 family 이름으로 글꼴을 참조합니다.

_brand.yml

typography:
  fonts:
    - family: Jura
      source: google
  base: Jura
  headings: Jura

base는 본문 기본 글꼴, headings는 제목 글꼴을 지정합니다. links로 링크 스타일을 바꿀 수 있으며, monospace는 코드 전반의 글꼴을 설정합니다. monospace-inline, monospace-block을 이용해 인라인/블록 코드의 스타일을 개별적으로 지정할 수 있습니다.

_brand.yml

typography:
  fonts:
    - family: Jura
      source: google
    - family: Space Mono
      source: google
  base: Jura
  headings: Jura
  link:
    decoration: underline
  monospace: Space Mono
  monospace-inline:
    color: "#222222"
    background-color: "#ddeaf1" # or use a named color from `color`
  monospace-block: 
    background-color: "#eef4f8"

각 요소마다 허용되는 속성이 다르므로 아래 Callout을 펼쳐 확인하세요.

타이포그래피 요소 및 지원 속성

typography에서 스타일링할 수 있는 전체 요소와 지원 속성은 다음과 같습니다.

속성	설명	지원 속성 \|
`base`	기본 텍스트로, 주로 문서 본문에 사용됩니다. \| - `family` \| - `size` \| - `line-height` \| - `weight`
`headings`	모든 제목 레벨(h1, h2 등)입니다.	`family` `weight` `style` `line-height` `color`
`monospace`	일반 고정폭 텍스트로, 보통 코드 블록과 기타 프로그래밍 관련 콘텐츠에 사용됩니다.	`family` `size` `weight`
`monospace-inline`	인라인 고정폭 텍스트로, 보통 일반 텍스트 내 코드 조각에 사용됩니다. `monospace`를 상속합니다.	`family` `size` `weight` `color` `background-color`
`monospace-block`	블록(여러 줄) 고정폭 텍스트로, 보통 코드 블록에 사용됩니다. `monospace`를 상속합니다.	`family` `size` `weight` `line-height` `color` `background-color`
`link`	하이퍼링크입니다.	`weight` `color` `background-color` `decoration`

각 속성은 아래와 같이 이해하면 됩니다.

family: 사용할 글꼴 패밀리(typography.fonts에 정의된 이름과 일치해야 함)
size: 글꼴 크기(CSS 단위 사용)
weight: 글꼴 두께(100~900 또는 normal, bold 등)
style: 글꼴 스타일(normal, italic 등)
line-height: 줄 간격(배수 또는 고정 단위)
color: 텍스트 색상(CSS 색상 또는 팔레트 참조)
background-color: 배경색(CSS 색상 또는 팔레트 참조)
decoration: 텍스트 장식(주로 링크에 사용, 예: underline, none)

Typst

Typst 구현 및 글꼴 문제 해결은 고급 문서를 참고하세요.

기본값

기본값 관련 문서

brand.yml의 defaults 섹션은 스펙에 직접 포함되지 않는 도구별 옵션을 지정할 때 사용합니다. 현재 Quarto는 defaults: bootstrap을 지원합니다.

Bootstrap

defaults 안의 bootstrap 섹션은 공식 스펙을 따르며 html, dashboard 포맷에 적용됩니다. Quarto는 defaults: bootstrap에서 지정한 옵션을 SCSS 레이어링 시스템의 적절한 레이어에 병합합니다.

bootstrap 내부의 defaults는 문자열 또는 SCSS 변수명-값 쌍을 받습니다. 앞선 예제를 바탕으로 link-decoration, navbar-fg SCSS 변수를 설정할 수 있습니다.

_brand.yml

defaults:
  bootstrap:
    defaults: # defaults also supports a string as its value
      link-decoration: underline
      navbar-fg: "#fff"

이렇게 하면 HTML 페이지의 링크가 밑줄로 표시되고 네비게이션 바 텍스트가 흰색으로 변경됩니다.

defaults: bootstrap 설정 없음

defaults: bootstrap 설정 적용: 링크 장식과 내비게이션 바 텍스트의 흰색을 확인하세요

defaults 외에도 uses, functions, mixins, rules 옵션을 문자열 값으로 지정할 수 있습니다. 예를 들어 rules에 CSS를 작성해 2단계 제목의 하단 테두리를 제거할 수 있습니다.

_brand.yml

defaults:
  bootstrap:
    # uses: <string>
    # functions: <string>
    # mixins: <string>
    rules: |
      h2 {
        border: none;
      }

메타

메타 데이터 문서

meta 키로 브랜드 메타데이터를 설정할 수 있습니다(현재 Quarto는 이 값을 사용하지 않음).

`_brand.yml` 값 사용하기

브랜드 파일을 자동으로 적용하는 것 외에도 Quarto 문서에서 _brand.yml 값을 직접 참조할 수 있습니다. 이 섹션에서는 brand 숏코드 사용법, SCSS 파일에서 브랜드 변수를 사용하는 방법, 그리고 형식별로 브랜드 값을 활용하는 방법을 설명합니다.

숏코드 - `{{< brand >}}`

_brand.yml 구성 파일의 일부 값은 brand 숏코드로 접근할 수 있습니다. 특히 색상과 로고는 이름으로 참조할 수 있습니다.

{{< brand color COLOR_NAME VARIANT >}}를 사용하면 COLOR_NAME으로 지정한 브랜드 색상을 문자열로 반환합니다.
{{< brand logo LOGO_NAME VARIANT >}}를 사용하면 LOGO_NAME으로 지정한 브랜드 로고를 이미지로 반환합니다.

VARIANT는 선택 사항입니다.

brand color 숏코드는 기본값이 light입니다. dark brand의 색상을 반환하려면 dark를 사용합니다.
brand logo 숏코드는 기본값이 both이며, 적절한 모드별 콘텐츠 클래스를 포함한 라이트/다크 로고를 모두 확장합니다. 따라서 라이트 모드에서는 라이트 로고가, 다크 모드에서는 다크 로고가 표시됩니다.

Note

VARIANT가 light 또는 dark이면 brand logo 숏코드는 모드별 클래스를 추가하지 않습니다.

예를 들어 숏코드를 사용해 icon이라는 이름의 브랜드 이미지를 대시보드 사이드바에 배치할 수 있습니다.

dashboard.qmd

---
format: dashboard
---

## Inputs {.sidebar}

{{< brand logo icon >}}

또는 숏코드를 사용해 revealjs 슬라이드의 배경색을 primary 브랜드 색상으로 지정할 수도 있습니다.

slides.qmd

---
format: revealjs
---

## Slide Title {background-color='{{< brand color primary >}}'}

제한 사항

현재 brand 숏코드로 typography, meta, defaults 값은 참조할 수 없습니다.

SCSS에서 사용하기

palette에 정의된 색상은 brand-COLOR_NAME 형태의 SCSS 변수로 노출됩니다. 예를 들어 _brand.yml에 blue를 정의했다면,

_brand.yml

color:
  palette:
    blue: "#ddeaf1"

$brand-blue 변수가 Quarto SCSS 레이어 시스템의 defaults 레이어에서 #ddeaf1로 설정됩니다. 일반적인 방법으로 사용자 정의 SCSS 파일(styles.scss)을 추가한 다음

_quarto.yml

format:
  html:
    theme: [styles.scss]

styles.scss에서 이 변수를 사용해 스타일을 조정할 수 있습니다. 예를 들어 모든 h1 색상을 파란색으로 설정하려면:

styles.scss

/*-- scss:rules --*/

h1 {
  color: $brand-blue;
}

명시적으로 brand를 나열하지 않고 SCSS 파일을 지정하면, 내부적으로 brand 이후에 추가한 것과 동일하게 처리됩니다. 예를 들어 앞서의 theme 설정은 다음과 같습니다.

_quarto.yml

format:
  html:
    theme: [brand, styles.scss]

theme 항목의 순서는 적용 우선순위를 결정합니다. 내장 테마 위에 브랜드와 커스텀 SCSS를 차례로 쌓을 수도 있습니다.

_quarto.yml

format:
  html:
    theme: [cosmo, brand, styles.scss]

테마 레이어링에 대한 자세한 내용은 Quarto 테마 심화를 참고하세요.

Typst

Typst 문서에서는 브랜드 색상이 brand-color 딕셔너리에 저장됩니다. Raw Typst 블록에서 brand-color.COLOR_NAME 문법으로 바로 사용할 수 있습니다. 예를 들어 primary 색으로 채운 사각형을 만들려면:

document.qmd


```{=typst}
#rect(fill: brand-color.primary)
```

브랜드 로고는 brand-logo, brand-logo-images 딕셔너리에 저장됩니다. 다음처럼 Typst 코드에서 경로와 alt 텍스트를 참고해 이미지를 삽입할 수 있습니다.

document.qmd

---
format: typst
brand:
  logo:
    images:
      custom:
        path: custom.png
        alt: custom logo
---

```{=typst}
#image(brand-logo-images.custom.path, alt=brand-logo-images.custom.alt)
```

Lua API

필터와 숏코드는 brand Lua 모듈을 사용해 브랜드 값을 조회할 수 있습니다.

local brand = require('modules/brand/brand')
local primary = brand.get_color('primary')

브랜드 공유

Warning

Quarto 프로젝트의 모든 자산(로고, 글꼴 등)은 루트에 _quarto.yml이 있는 단일 디렉터리 트리에 있어야 합니다. 그 외 위치의 brand.yml을 참조하면 제대로 동작하지 않습니다.

Quarto 1.8에서는 Git 저장소 형태로 브랜드 메타데이터/자산을 배포할 수 있는 브랜드 확장을 소개했습니다.

확장은 프로젝트의 _extensions/ 하위에 설치되며, 각 프로젝트마다 브랜드 데이터 사본이 존재합니다. 저장소 변경 사항은 quarto update로 갱신하세요.

Quarto 1.9에서는 브랜드 공유를 단순화하는 quarto use brand 명령이 도입될 예정입니다. 출시 시점은 사전 출시 문서를 참고하세요.

브랜드와 테마 결합

Note

아래 내용은 _brand.yml을 bootswatch 테마와 함께 사용하려는 경우에만 필요합니다.

기존 프로젝트를 Quarto 1.6 _brand.yml 구조로 이전하는 방법은 간단합니다. Quarto 1.5 이하에서는 bootswatch 테마에 사용자 정의 .scss를 추가하는 방식이 일반적이었습니다. 예를 들어 Quarto 1.5의 _quarto.yml은 다음과 같았습니다.

# Quarto 1.5 syntax
theme:
  - cosmo       # a predefined bootswatch theme
  - tweaks.scss # a user-defined customization

Quarto 1.6에서 _brand.yml을 사용하면 브랜드 스타일이 항상 가장 낮은 우선순위를 가집니다. 즉, 위 설정은 다음과 동일합니다.

# Quarto 1.6 syntax
theme:
  - brand        # theming derived from `_brand.yml`
  - cosmo        # a predefined bootswatch theme
  - tweaks.scss  # a user-defined customization

따라서 brand에서 정의한 값이 cosmo나 tweaks.scss에 의해 덮어쓸 수 있습니다. 필요한 경우도 있지만 브랜드를 더 우선시하고 싶다면 순서를 다음처럼 바꾸세요.

# Quarto 1.6 syntax
theme:
  - cosmo        # a predefined bootswatch theme
  - brand        # theming derived from `_brand.yml`
  - tweaks.scss  # a user-defined customization

라이트/다크 브랜드와 테마를 조합할 때도 동일한 개념을 적용할 수 있습니다.

# Quarto 1.7 syntax
theme:
  light:
    - cosmo
    - brand
  dark:
    - slate
    - brand

Quarto 스타일 생성 방식에 대한 자세한 설명은 Quarto 테마 심화에서 확인하세요.

개요

브랜드 적용

라이트/다크 색상

라이트/다크 브랜드

브랜드 모드

브랜드 요소

색상

로고

라이트/다크 로고

문서 수준 로고 설정

타이포그래피

Typst

기본값

Bootstrap

메타

_brand.yml 값 사용하기

숏코드 - {{< brand >}}

SCSS에서 사용하기

Typst

Lua API

브랜드 공유

브랜드와 테마 결합

`_brand.yml` 값 사용하기

숏코드 - `{{< brand >}}`