HTML 기본

개요

html 포맷을 사용해 HTML 출력을 생성합니다. 예:

---
title: "My document"
format:
  html:
    toc: true
    html-math-method: katex
    css: styles.css
---

이 예시는 HTML 출력에 사용할 수 있는 몇 가지 옵션을 보여줍니다. 이 문서에서는 이러한 옵션과 다른 옵션을 자세히 설명합니다. 전체 옵션 목록은 HTML 포맷 참조를 참고하세요.

목차

toc 옵션을 사용하면 출력 문서에 자동 생성된 목차가 포함됩니다. toc-depth 옵션으로 목차에 포함할 섹션 수준을 지정할 수 있습니다. 기본값은 3이며(즉, 1, 2, 3단계 제목이 목차에 표시됩니다) 예시는 다음과 같습니다.

toc: true
toc-depth: 2

toc-expand 옵션으로 목차를 처음에 얼마나 펼쳐서 보여줄지 지정할 수 있습니다(기본값은 1이며 스크롤에 따라 자동 확장). 모두 펼치려면 true, 모두 접으려면 false를 사용합니다.

toc: true
toc-expand: 2

toc-title 옵션으로 목차 제목을 사용자 지정할 수 있습니다.

toc-title: Contents

목차에서 특정 제목을 제외하려면 .unnumbered와 .unlisted 클래스를 모두 추가합니다.

### More Options {.unnumbered .unlisted}

HTML 포맷은 기본적으로 목차를 오른쪽에 띄웁니다. 대신 left 또는 body에 배치할 수 있습니다. 예:

format:
  html:
    toc: true
    toc-location: left

본문과 좌/우 플로팅 목차를 동시에 표시하려면 각각 left-body 또는 right-body를 지정합니다.

플로팅 목차는 섹션 탐색에 사용되며, 사용자가 스크롤할 때 해당 섹션이 자동으로 강조 표시됩니다. 목차는 반응형이며 뷰포트가 좁아지면 숨겨집니다. 이 페이지 오른쪽에서 예시를 확인할 수 있습니다.

표준 HTML 테마를 비활성화한 경우(예: theme: none 또는 theme: pandoc) toc-location 옵션을 사용할 수 없습니다.

섹션 번호

number-sections 옵션을 사용하면 출력 문서의 섹션 제목에 번호가 붙습니다. 예:

number-sections: true

number-depth 옵션으로 번호를 붙일 가장 깊은 제목 수준을 지정할 수 있습니다(기본값은 모든 제목에 번호가 붙음). 예:

number-depth: 3

개별 제목에 번호를 붙이지 않으려면 .unnumbered 클래스를 추가합니다.

### More Options {.unnumbered}

코드 링크와 기타 링크

code-links와 other-links를 사용하면 페이지 네비게이션에서 각각 “Code Links”, “Other Links” 아래에 표시될 링크를 추가할 수 있습니다. 예를 들어 다음과 같은 문서 YAML 헤더가 있습니다.

---
format:
  html:
    other-links:
      - text: NASA Open Data
        href: https://data.nasa.gov/
    code-links:
      - text: Data Import Code
        icon: file-code
        href: data-import.py
---

렌더링하면 다음과 같이 표시됩니다.

HTML 페이지 스크린샷. 오른쪽 목차 아래에 'Other Links'와 'Code Links' 헤더가 보이며, 각각 'NASA Open Data'와 'Data Import Code' 링크가 표시된다.

code-links와 other-links 항목에는 다음 옵션을 제공할 수 있습니다.

옵션 설명
text 링크에 표시할 텍스트입니다.
href 링크의 URL입니다.
icon 링크에 사용할 bootstrap 아이콘입니다.
rel 이 링크의 a 태그에 사용할 rel입니다.
target 이 링크의 a 태그에 사용할 target입니다.

GitHub 및 Binder 링크

프로젝트의 경우 code-links 항목으로 전달할 수 있는 특별한 값이 두 가지 있습니다.

repo

프로젝트의 GitHub 리포지토리를 가리키는 “GitHub Repo” 링크를 “Code Links” 아래에 추가합니다.

binder

프로젝트가 Binder 사용으로 구성된 경우 “Code Links” 아래에 “Launch Binder” 링크를 추가합니다.

CSS 스타일

문서에 CSS 스타일시트를 추가하려면 css 옵션을 지정하면 됩니다. 예:

format:
  html: 
    css: styles.css

css 옵션은 문서 모양을 간단히 조정하는 데 적합합니다. 더 광범위한 커스터마이징은 HTML 테마 문서를 참고하세요.

LaTeX 수식

기본적으로 LaTeX 수식은 MathJax로 렌더링됩니다. 다른 방법을 선택하려면 html-math-method 옵션을 사용합니다. 예:

format:
  html:
    html-math-method: katex

특정 방법에서 로드할 라이브러리의 url을 지정할 수도 있습니다.

html-math-method:
  method: mathjax
  url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"

사용 가능한 수식 렌더링 방법은 다음과 같습니다.

Method Description
mathjax MathJax로 HTML 출력에 포함된 TeX 수식을 표시합니다. MathJax의 기본 구성은 tex-chtml-full.js이며 colorv2, physics를 제외한 모든 MathJax 확장을 로드합니다(physics는 \require{physics}로 사용 가능).
katex KaTeX로 HTML 출력에 포함된 TeX 수식을 표시합니다.
webtex TeX 수식을 이미지로 변환하는 외부 스크립트에 연결된 <img> 태그로 변환합니다.
gladtex HTML 출력에서 TeX 수식을 <eq> 태그로 감쌉니다. 결과 HTML은 GladTeX로 처리되어 조판된 수식 이미지와 링크가 포함된 HTML을 생성합니다.
mathml TeX 수식을 MathML로 변환합니다.
plain 특별한 처리 없이 class="math"인 span 안에 수식을 넣습니다.

각 옵션의 자세한 내용은 Pandoc HTML에서 수식 렌더링 문서를 참고하세요.

탭셋

탭셋을 사용하면 대상 독자에 따라 관심이 달라질 콘텐츠를 제시할 수 있습니다. 예를 들어 다양한 언어의 코드 예제를 제공합니다.

fizz_buzz <- function(fbnums = 1:50) {
  output <- dplyr::case_when(
    fbnums %% 15 == 0 ~ "FizzBuzz",
    fbnums %% 3 == 0 ~ "Fizz",
    fbnums %% 5 == 0 ~ "Buzz",
    TRUE ~ as.character(fbnums)
  )
  print(output)
}
def fizz_buzz(num):
  if num % 15 == 0:
    print("FizzBuzz")
  elif num % 5 == 0:
    print("Buzz")
  elif num % 3 == 0:
    print("Fizz")
  else:
    print(num)
public class FizzBuzz
{
  public static void fizzBuzz(int num)
  {
    if (num % 15 == 0) {
      System.out.println("FizzBuzz");
    } else if (num % 5 == 0) {
      System.out.println("Buzz");
    } else if (num % 3 == 0) {
      System.out.println("Fizz");
    } else {
      System.out.println(num);
    }
  }
}
function FizzBuzz(num)
  if num % 15 == 0
    println("FizzBuzz")
  elseif num % 5 == 0
    println("Buzz")
  elseif num % 3 == 0
    println("Fizz")
  else
    println(num)
  end
end

panel-tabset 클래스를 가진 마크다운 div(예: ::: {.panel-tabset})로 탭셋을 만듭니다. div 안의 최상위 제목은 각각 새 탭이 됩니다. 예를 들어 위의 첫 두 개 탭을 구현하는 마크다운은 다음과 같습니다.

::: {.panel-tabset}
## R

``` {.r}
fizz_buzz <- function(fbnums = 1:50) {
  output <- dplyr::case_when(
    fbnums %% 15 == 0 ~ "FizzBuzz",
    fbnums %% 3 == 0 ~ "Fizz",
    fbnums %% 5 == 0 ~ "Buzz",
    TRUE ~ as.character(fbnums)
  )
  print(output)
}
```

## Python

``` {.python}
def fizz_buzz(num):
  if num % 15 == 0:
    print("FizzBuzz")
  elif num % 5 == 0:
    print("Buzz")
  elif num % 3 == 0:
    print("Fizz")
  else:
    print(num)
```

:::

탭셋 그룹

같은 탭 이름을 포함하는 여러 탭셋이 있다면 group을 정의할 수 있습니다. group 안의 탭은 함께 전환됩니다(즉, 위 예시에서 한 탭셋을 R이나 Python으로 바꾸면 다른 탭셋도 함께 바뀝니다). 예:

::: {.panel-tabset group="language"}
## R

Tab content

## Python

Tab content
:::

활성 탭셋

기본적으로 탭셋의 첫 번째 탭이 페이지 로드 시 활성화됩니다. 로드 시 다른 탭을 활성화하려면 탭 제목에 .active 클래스를 추가하세요. 예를 들어 아래에서는 “Python” 탭이 로드 시 활성화됩니다.

::: {.panel-tabset}
## R

Tab content

## Python {.active}

Tab content
:::

자체 포함

HTML 문서는 보통 이미지, CSS 스타일시트, JavaScript 등 여러 외부 의존성을 갖습니다. 기본적으로 이러한 의존성은 문서 옆의 _files 디렉터리에 배치됩니다. 예를 들어 report.qmd를 HTML로 렌더링하면:

Terminal
quarto render report.qmd --to html

다음과 같은 출력이 생성됩니다.

report.html
report_files/

이미지, CSS, JavaScript 등을 HTML 파일 안에 포함한 완전한 단일 HTML 문서를 만들고 싶을 수도 있습니다. embed-resources 옵션을 지정하면 됩니다.

format:
  html:
    embed-resources: true

이렇게 하면 외부 의존성이 없는 단일 HTML 파일이 생성되며, data: URI로 연결된 스크립트, 스타일시트, 이미지, 비디오 내용을 포함합니다. 결과 파일은 외부 파일이나 네트워크 접근 없이도 브라우저에서 제대로 표시되는 자체 포함 파일입니다.

앵커 섹션

섹션 제목에 마우스를 올리면 앵커 링크가 표시됩니다. 이 동작은 다음으로 켜고 끌 수 있습니다.

format:
  html:
    anchor-sections: true

앵커 링크는 상호 참조가 정의된 그림과 표에도 자동으로 추가됩니다.

부드러운 스크롤

페이지 내 부드러운 스크롤을 활성화합니다. 기본값은 비활성화이며 다음으로 켜고 끌 수 있습니다.

format:
  html:
    smooth-scroll: true

외부 링크

기본적으로 외부 링크(현재 사이트가 아닌 링크)는 별도의 시각적 표시나 탐색 처리를 하지 않으며 현재 페이지에서 이동합니다. 다음 옵션으로 이 동작을 변경할 수 있습니다.

옵션 | 설명 |
link-external-icon 외부 링크임을 나타내는 아이콘을 링크 옆에 표시하려면 true(예: external).
link-external-newwindow 외부 링크를 새 창/탭에서 열려면 true(현재 탭 이동 대신).
link-external-filter

링크가 내부 링크인지 판단하는 데 사용할 정규식. 예:

^(?:http:|https:)\/\/www\.quarto\.org\/custom

http://www.quarto.org로 시작하는 링크를 내부 링크로 처리합니다(그 외는 외부 링크로 처리).

외부 링크는 site-url이 있으면 이를 사용해 판단하며, 없으면 window.host를 사용합니다(site-url과 link-external-filter가 모두 없을 때). 예를 들어 다음은 두 옵션과 커스텀 필터를 활성화한 예입니다.

format:
  html:
    link-external-icon: true
    link-external-newwindow: true
    link-external-filter: '^(?:http:|https:)\/\/www\.quarto\.org\/custom'

.external 클래스와 target 속성을 사용해 개별 링크에 이 동작을 지정할 수도 있습니다. 예:

[example](https://example.com){.external target="_blank"}

참고 팝업

이 문장에서 인용, 각주, 상호 참조에 마우스를 올리면 참고 내용을 표시하는 팝업이 나타납니다.

   Xie (2015) 에 마우스를 올리면 knitr의 결정적 참고서에 대한 인용을 볼 수 있습니다1. Listing 1 는 호버 동작을 끄는 방법을 보여줍니다.

이 동작은 기본으로 활성화되어 있습니다. 다음 옵션으로 비활성화할 수 있습니다.

Listing 1 
format:
  html:
    citations-hover: false
    footnotes-hover: false
    crossrefs-hover: false

댓글

이 페이지는 다음 YAML 옵션으로 Hypothes.is 댓글이 활성화되어 있습니다.

comments:
  hypothesis: true

페이지 오른쪽 끝에서 Hypothesis UI를 볼 수 있습니다. true 대신 hypothesis의 하위 키로 사용 가능한 Hypothesis 임베딩 옵션을 지정할 수 있습니다. 예:

comments:
  hypothesis: 
    theme: clean

utterances 옵션으로 Utterances 댓글을 활성화할 수 있습니다. 이때 댓글을 저장할 GitHub 리포지토리를 최소한 지정해야 합니다.

comments:
  utterances:
    repo: quarto-dev/quarto-docs

다른 옵션은 여기에 문서화되어 있습니다.

giscus 옵션으로 Giscus 댓글도 활성화할 수 있습니다. Giscus는 GitHub 리포지토리의 Discussions에 댓글을 저장합니다.

comments:
  giscus: 
    repo: quarto-dev/quarto-docs

Utterances와 마찬가지로 댓글을 저장할 Git 리포지토리를 최소한 지정해야 합니다. 또한 사용하는 리포지토리는 다음 조건을 충족해야 합니다.

  1. 공개 리포지토리

  2. Giscus 앱 설치

  3. Discussion 활성화

리포지토리에 Giscus를 설정하는 방법은 Giscus 문서를 참고하세요. 추가 옵션은 여기에 설명되어 있습니다.

댓글 비활성화

전체 웹사이트나 책에서 댓글을 활성화했더라도 comments: false로 특정 페이지의 댓글을 비활성화할 수 있습니다. 예:

title: "Home Page"
comments: false

포함

다른 파일의 추가 콘텐츠를 문서에 포함하려면 include-in-* 옵션을 사용할 수 있습니다.

옵션 설명
include-in-header 헤더 끝에 file의 내용을 그대로 포함합니다. 예를 들어 HTML 문서에 특수 CSS/JavaScript를 포함하거나 LaTeX 프리앰블에 명령을 삽입하는 데 사용할 수 있습니다.
include-before-body 문서 본문 시작 부분에 file의 내용을 그대로 포함합니다(HTML에서는 <body> 태그 뒤, LaTeX에서는 \begin{document} 뒤). HTML 문서에 내비게이션 바나 배너를 넣는 데 사용할 수 있습니다.
include-after-body 문서 본문 끝에 file의 내용을 그대로 포함합니다(HTML에서는 </body> 태그 앞, LaTeX에서는 \end{document} 앞).

각 옵션에 대해 파일 하나 또는 여러 파일을 직접 지정하거나 file: 하위 키를 사용할 수 있습니다. YAML 헤더에 원시 콘텐츠를 포함하려면 text 하위 키를 사용하세요. text:를 사용할 때는 text: 뒤에 | 문자를 추가해 다중 줄 문자열임을 나타냅니다. file:이나 text:를 생략하면 Quarto는 파일을 제공하는 것으로 간주합니다.

예:

format:
  html:
    include-in-header:
      - text: |
          <script src="https://examples.org/demo.js"></script>
      - file: analytics.html
      - comments.html
    include-before-body: header.html

최소 HTML

기본 Quarto HTML 출력 포맷은 bootstrap 테마, 앵커 섹션, 참고 팝업, 탭셋, 코드 블록 복사, 반응형 그림 등 여러 기능을 포함합니다. minimal 옵션으로 이러한 내장 기능을 한 번에 비활성화할 수 있습니다. 예:

---
title: "My Document"
format:
  html:
    minimal: true
---

minimal: true를 지정하더라도 원하는 기능만 선택적으로 다시 활성화할 수 있습니다. 예:

---
title: "My Document"
format:
  html:
    minimal: true
    code-copy: true
---

References

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. https://yihui.name/knitr/.

Footnotes

  1. knitr는 동적 문서를 만들기 위한 R 패키지입니다.↩︎