HTML 테마

개요

Quarto로 렌더링한 HTML 문서는 기본적으로 Bootstrap 5를 사용합니다. theme 옵션으로 비활성화하거나 커스터마이즈할 수 있습니다.

theme: default # bootstrap 5 default
theme: cosmo   # cosmo bootswatch theme
theme: pandoc  # pandoc default html treatment
theme: none    # no theme css added to document

Quarto에는 Bootswatch 프로젝트의 25개 테마가 포함되어 있습니다(예: 이 웹사이트는 cosmo 테마를 사용). 사용 가능한 테마는 다음과 같습니다.

theme 옵션으로 이들 테마를 사용할 수 있습니다. 예:

format:
  html:
    theme: united

이 테마들을 커스터마이즈하거나 새 테마를 만들 수도 있습니다. 방법은 아래의 테마 옵션에서 설명합니다.

기본 옵션

Bootstrap 테마나 Pandoc 테마를 사용하는 경우, 문서 메타데이터에 옵션을 지정해 모양을 커스터마이즈할 수 있습니다. 예를 들면 다음과 같습니다.

Option Description
max-width The maximum width occupied by page content. Defaults to 1400px for bootstrap themes and 36em for the pandoc theme.
mainfont 문서의 font-family 속성을 설정합니다. |
fontsize 문서의 기본 CSS font-size를 설정합니다. |
fontcolor 문서의 기본 텍스트 color를 설정합니다. |
linkcolor 하이퍼링크의 기본 텍스트 color를 설정합니다. |
monofont <code> 요소의 font-family 속성을 설정합니다. |
monobackgroundcolor <code> 요소의 background-color 속성을 설정합니다. |
linestretch CSS line-height 속성을 설정합니다(텍스트 줄 간격에 영향을 주며 기본값은 1.5). |
backgroundcolor 문서의 background-color를 설정합니다. |
margin-left, margin-right, margin-top, margin-bottom 문서 본문의 CSS margin 속성을 설정합니다. |

예를 들어 글자 크기를 조금 키우고 줄 간격을 더 넓게 설정하려면 다음과 같이 합니다.

title: "My Document"
format:
  html: 
    theme: cosmo
    fontsize: 1.1em
    linestretch: 1.7

테마 옵션

Sass를 사용하면 테마를 폭넓게 커스터마이즈할 수 있습니다. Bootstrap에는 글꼴, 색상, 패딩, 테두리 등을 제어하는 1,400개 이상의 Sass 변수가 있습니다. 모든 변수는 아래에서 확인할 수 있습니다.

https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss

Sass 테마 파일은 색상과 글꼴 등을 전역으로 설정하는 variables와, 더 세밀한 동작을 정의하는 rules를 모두 정의할 수 있습니다. 기존 Bootstrap 테마를 변수/규칙으로 커스터마이즈하려면 기본 테마와 커스텀 테마 파일을 함께 지정하면 됩니다.

theme:
  - cosmo
  - custom.scss

custom.scss 파일은 다음과 같이 구성할 수 있습니다.

/*-- scss:defaults --*/
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
}

variables 섹션은 /*-- scss:defaults --*/ 주석으로, rules 섹션(일반 CSS 규칙이 들어가는 부분)은 /*-- scss:rules --*/ 주석으로 표시합니다.

커스텀 테마

완전히 커스텀 테마를 만들어 그것만 제공할 수도 있습니다(이 경우 기본 Bootstrap 테마를 상속합니다).

theme: custom.scss

예를 들어 25개의 내장 Bootswatch 테마 파일은 다음과 같습니다.

https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/html/bootstrap/themes

커스텀 테마 설계에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

다크 모드

HTML 출력에 단일 테마를 제공하는 것 외에도 라이트/다크 테마를 함께 제공할 수 있습니다. 예:

theme:
  light: flatly
  dark: darkly

위 테마를 _quarto.yml에 설정하면 라이트/다크 버전 출력이 모두 제공됩니다. 예:

Flatly 테마 출력

이 페이지의 라이트 버전 헤더에 Flatly 테마가 적용된 스크린샷.

Darkly 테마 출력

이 페이지의 다크 버전 헤더에 Darkly 테마가 적용된 스크린샷.

HTML 출력에 라이트/다크 모드를 모두 제공하면 Quarto가 독자가 원하는 모드를 선택할 수 있는 토글을 자동으로 생성합니다. 이 토글은 HTML 출력의 오른쪽 상단에 자동으로 표시되며, 가능한 경우 브라우저의 로컬 스토리지를 사용해 사용자 선호를 세션 간 유지합니다.

사용자의 운영체제/브라우저 라이트·다크 모드 선호를 존중하려면 respect-user-color-scheme: true를 지정하세요.

format:
  html:
    respect-user-color-scheme: true

그렇지 않으면 테마 또는 브랜드에서 라이트/다크 요소의 순서가 HTML 출력의 기본 모양을 결정합니다. 예를 들어 첫 번째 예시에서 light 옵션이 먼저 나오므로 respect-user-color-scheme를 사용하지 않으면 기본으로 라이트 모드가 표시됩니다.

가능한 경우 Quarto는 지정한 텍스트 하이라이터의 라이트/다크 버전을 자동으로 선택합니다. 자세한 내용은 코드 하이라이팅을 참고하세요.

Quarto 1.7부터 respect-user-color-scheme는 JavaScript 지원이 필요합니다. JavaScript가 비활성화된 사용자는 작성자가 선호하는(첫 번째) 브랜드 또는 테마를 보게 됩니다.

모드별 콘텐츠

라이트 모드에서만 콘텐츠를 표시하려면 .light-content CSS 클래스를, 다크 모드에서만 표시하려면 .dark-content 클래스를 사용합니다.

보통 라이트/다크 콘텐츠는 같은 위치와 같은 크기로 제공해야 모드 전환 시 페이지 레이아웃이 변하지 않습니다.

예를 들어 다음 코드가 생성하는 문단은 라이트/다크 모드에서 서로 다른 텍스트를 표시합니다.

::: {.light-content}
이 텍스트는 라이트 모드에서 표시됩니다.
:::

::: {.dark-content}
이 텍스트는 다크 모드에서 표시됩니다.
:::

This text will be shown in light mode.

This text will be shown in dark mode.

문서의 body 요소는 라이트 모드일 때 .quarto-light, 다크 모드일 때 .quarto-dark 클래스를 갖습니다.

CSS 규칙은 body에 .quarto-dark가 있으면 .light-content 요소를 숨기고, body에 .quarto-light가 있으면 .dark-content 요소를 숨깁니다.

셀 렌더링 기능은 플롯과 표 같은 계산 출력에 .light-content와 .dark-content CSS 클래스를 적용합니다.

테마 커스터마이징

단일 테마를 제공할 때와 마찬가지로 라이트/다크 모드에 대한 커스텀 테마를 제공하거나, 라이트/다크 모양을 커스터마이즈하는 scss 파일 목록을 지정할 수 있습니다. 예를 들어 이 웹사이트는 라이트 모드에 cosmo 테마를 사용하고 다크 모드에서는 추가 Sass 변수로 cosmo 테마를 커스터마이즈합니다.

theme:
  light: [cosmo, theme.scss]
  dark: [cosmo, theme-dark.scss]

아래는 라이트 cosmo 테마를 다크로 바꾸는 theme-dark.scss의 일부입니다.

/*-- scss:defaults --*/
// Base document colors
$body-bg: #181818;
$body-color: #ccc;
$link-color: #75AADB;

// Code blocks
$code-block-bg-alpha: -.9;

사용 가능한 Sass 변수에 대한 자세한 내용은 Sass 변수로 HTML 커스터마이즈 문서를 참고하세요.

Sass 변수

다음 Sass 변수는 SCSS 파일에서 지정할 수 있습니다(이 변수는 항상 $ 접두사를 붙여야 하며 YAML 옵션이 아니라 테마 파일에 지정합니다).

색상

변수 설명 |
$body-bg 페이지 배경색.
$body-color 페이지 텍스트 색상.
$link-color 링크 색상.
$input-bg HTML 입력 요소의 배경색.
$popover-bg 팝오버 배경색(예: 인용 미리보기가 표시될 때).

글꼴

변수 설명 |
$font-family-sans-serif 페이지의 산세리프 글꼴 패밀리. |
$font-family-monospace 페이지의 모노스페이스 글꼴 패밀리. |
$font-size-root 페이지 기본 글꼴 크기.
$toc-font-size 페이지 목차 글꼴 크기.

$h1-font-size

$h2-font-size

$h3-font-size

$h4-font-size

$h5-font-size

 해당 제목의 글꼴 크기.

코드 블록

변수 설명 |
$code-block-border-left 기본적으로 Quarto는 코드 블록에 왼쪽 테두리를 표시하지 않습니다. 이 변수를 참 값 또는 CSS 색상으로 설정하면 왼쪽 테두리가 활성화됩니다. |
$code-block-border-left-style 코드 블록에 표시되는 왼쪽 테두리 스타일. 기본값은 solid. |
$code-block-border-left-size 코드 블록에 표시되는 왼쪽 테두리 두께. 기본값은 3px. |
$code-block-padding-left 코드와 테두리 사이의 왼쪽 패딩. 기본값은 0.6em. |
$code-block-bg 기본적으로 Quarto는 테마의 progress-bg 색상에 투명도를 더해 코드 블록 배경을 설정합니다. 이 변수를 참 값 또는 CSS 색상으로 설정할 수 있습니다. |
$code-block-bg-padding 코드 블록에 적용되는 패딩. 기본값은 0.4em. |
$code-block-bg-alpha progress-bg 색상의 투명도 변경량. 명시적 배경색이 지정되면 사용되지 않습니다. 기본값은 -0.35. |

코드 주석

코드 주석을 사용할 때 강조 라인에 사용되는 색상을 커스터마이즈할 수 있습니다.

변수 설명 |
$code-annotation-higlight-color 강조된 라인의 테두리 색상. |
$code-annotation-higlight-bg 강조된 라인의 배경색. |

코드 복사

code-copy: true일 때 표시되는 버튼 색상도 다음 변수로 커스터마이즈할 수 있습니다.

변수 설명 |
$btn-code-copy-color 코드 블록 오른쪽 상단의 복사 버튼 색상. |
$btn-code-copy-color-active 코드 블록 오른쪽 상단 복사 버튼의 호버 색상. |

인라인 코드

변수 설명 |
$code-bg 인라인 코드 배경색. 기본값은 body-bg와 body-color의 혼합색. |
$code-color 인라인 코드 텍스트 색상. 기본값은 code-bg와 대비되는 색상으로 자동 생성됩니다. |

목차

변수 설명 |
$toc-color 목차 텍스트 색상. |
$toc-font-size 목차 텍스트 글꼴 크기. |
$toc-active-border 현재 활성 목차 항목의 왼쪽 테두리 색상. |
$toc-inactive-border 비활성 목차 항목의 왼쪽 테두리 색상.

레이아웃

변수 설명 |
$content-padding-top 메인 콘텐츠 영역(사이드바, 콘텐츠, 목차 포함) 앞에 들어갈 패딩. |

내비게이션

변수 설명 |
$navbar-bg 내비게이션 바 배경색. 기본값은 테마의 $primary 색상. |
$navbar-fg 내비게이션 바 전경 요소(텍스트 및 내비게이션) 색상. 지정하지 않으면 대비 색상이 자동으로 계산됩니다. |
$navbar-hl 내비게이션 바 링크 강조 색상. 지정하지 않으면 $link-color를 사용하거나 대비 색상이 자동으로 계산됩니다. |
$sidebar-bg 사이드바 배경색. 기본값은 $light이며, 내비게이션 바가 있거나 스타일이 floating인 경우 $body-bg가 기본값입니다. |
$sidebar-fg 사이드바 전경 요소(텍스트 및 내비게이션) 색상. 지정하지 않으면 대비 색상이 자동으로 계산됩니다. |
$sidebar-hl 사이드바 링크 강조 색상. 지정하지 않으면 $link-color가 사용됩니다. |
$footer-bg 푸터 배경색. 기본값은 $body-bg 색상입니다. |
$footer-fg 푸터 전경 요소(텍스트 및 내비게이션) 색상. 지정하지 않으면 대비 색상이 자동으로 계산됩니다. |

콜아웃

변수 설명 |
$callout-border-width 콜아웃 왼쪽 테두리 너비. 기본값은 5px. |
$callout-border-scale 콜아웃 색상에서 이 값만큼 이동해 계산한 테두리 색상. 기본값은 0%. |
$callout-icon-scale 콜아웃 색상에서 이 값만큼 이동해 계산한 아이콘 색상. 기본값은 10%. |
$callout-margin-top 콜아웃의 위쪽 마진. 기본값은 1.25rem.
$callout-margin-bottom 콜아웃의 아래쪽 마진. 기본값은 1.25rem. |
$callout-color-<type>

다양한 콜아웃 유형의 색상. 기본값: |

type default
note $blue
tip $green
caution $orange
warning $yellow
important $red

Bootstrap 변수

위의 Sass 변수 외에도 Bootstrap 자체에 수백 개의 추가 변수가 있습니다. Bootstrap의 Sass 변수 사용법을 확인하거나 원본 변수와 기본값을 참고하세요.