웹사이트 도구

헤더와 푸터

사이트 페이지에 표준 헤더와 푸터를 제공할 수 있습니다. 이들은 문서 본문 또는 사이드바에 적용될 수 있습니다. 사용 가능한 옵션은 다음과 같습니다:

Value Description
body-header 각 페이지 본문 시작(제목/작성자 블록 아래)에 삽입할 마크다운. |
body-footer 각 페이지 본문 아래에 삽입할 마크다운. |
margin-header 오른쪽 여백 콘텐츠(목차 등) 위에 삽입할 마크다운. |
margin-footer 오른쪽 여백 콘텐츠 아래에 삽입할 마크다운. |

예(_quarto.yml에 포함):

body-header: | 
  This page brought to you by <https://example.com>
margin-header: |
  ![Logo image](/img/logo.png)

그림 링크는 웹사이트 각 레벨에서 동작하려면 /로 시작해야 합니다.

공지 바

Quarto 웹사이트에 공지 바가 표시된 스크린샷. 'info-circle' 아이콘과 닫기 버튼이 있고, 기본 색상 스타일입니다. 내용은 'Alert - this is some information that you should pay attention to'입니다.

Quarto 웹사이트의 공지 바 기능을 보여주는 캡처.

웹사이트 상단에 눈에 띄는 맞춤형 바를 표시하는 공지를 추가할 수 있습니다. 경고, 프로모션, 업데이트 같은 중요한 정보를 강조하는 데 적합합니다. 아이콘을 설정할 수 있고, 닫기 가능 여부도 지정할 수 있으며, 굵게 같은 서식도 포함할 수 있습니다. 공지 바는 사이트 레이아웃에 맞게 below-navbar 또는 above-navbar 같은 위치로 배치할 수 있습니다.

예시 구성은 다음과 같습니다:

_quarto.yml
website:
  announcement: 
1    icon: info-circle
2    dismissable: true
3    content: "**Alert** - this is some information that you should pay attention to"
4    type: primary
5    position: below-navbar
1
icon - 공지 바에 표시할 Bootstrap 아이콘. Bootstrap icons 중에서 선택합니다.
2
dismissable - 사용자가 공지 바를 닫을 수 있는지 여부(true 또는 false).
3
content - 공지 바 내용. 마크다운 서식을 사용할 수 있습니다.
4
type - 공지 바 유형. primary, secondary, success, danger, warning, info, light, dark 중 하나.
5
position - 공지 바 위치. below-navbar 또는 above-navbar 중 하나.

소셜 메타데이터

다음과 같은 추가 메타데이터를 포함해 웹사이트와 콘텐츠를 더 풍부하게 만들 수 있습니다:

  • Favicon
  • Twitter Cards
  • Open Graph

웹사이트 도구를 사용할 때 중요한 점은, 이러한 도구를 웹사이트에서는 website 키 아래에 추가하지만 책에서는 동일한 옵션을 book 키 아래에 넣어야 한다는 것입니다. 예를 들어 웹사이트에서는 다음과 같이 파비콘과 트위터 카드를 추가합니다.

website:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

책에서는 book 키를 사용합니다.

book:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

아래 문서를 읽을 때 책을 작성 중이라면 website를 book으로 바꿔 생각하세요.

Favicon

사이트 파비콘은 브라우저 탭과 다른 사이트 링크에 표시되는 아이콘입니다. favicon 옵션으로 파비콘 이미지 경로를 지정합니다. 예:

website:
  favicon: logo.png

Twitter Cards

Twitter Cards는 Twitter에 링크가 공유될 때 더 풍부한 미리보기를 제공합니다. 트윗에 사이트 링크가 포함되면 Twitter가 사이트를 크롤링해 Twitter Card 메타데이터를 가져옵니다. Twitter Card 메타데이터 자동 생성을 활성화하려면 _quarto.yml에 다음을 추가합니다:

website:
  twitter-card: true

이 경우 Quarto는 콘텐츠에 대해 제목, 설명, 미리보기 이미지를 자동으로 생성합니다. Quarto가 미리보기 이미지를 찾는 방식은 [Preview Images]를 참고하세요.

Twitter Card 생성에 사용할 추가 메타데이터도 제공할 수 있습니다:

Key Description
title 페이지 제목. Quarto는 페이지 메타데이터의 title을 자동으로 사용합니다. Twitter Card에만 다른 제목을 쓰고 싶다면 twitter-card 메타데이터에 title을 지정합니다. |
description 콘텐츠의 짧은 설명. Quarto는 페이지 메타데이터의 description을 자동으로 사용합니다. Twitter Card에만 다른 설명을 쓰고 싶다면 twitter-card 메타데이터에 description을 지정합니다. |
image

콘텐츠 미리보기 이미지 경로. 기본적으로 문서 메타데이터의 image 값을 사용하고, 없으면 website: 메타데이터의 image 값을 사용합니다. | 이미지를 제공하면 image-width와 image-height로 Twitter Card 모양을 개선할 수 있습니다. |

image가 제공되지 않으면 Quarto가 미리보기 이미지를 자동으로 찾습니다. 자세한 내용은 [Preview Images]를 참고하세요. |
card-style summary 또는 summary_large_image. 지정하지 않으면 다른 메타데이터에 따라 적절한 스타일이 자동 선택됩니다. 자세한 내용은 여기를 참고하세요. |
creator 콘텐츠 작성자의 @username. @ 같은 특수 문자가 포함된 문자열은 YAML에서 따옴표로 감싸야 합니다. |
site 웹사이트의 @username. @ 같은 특수 문자가 포함된 문자열은 YAML에서 따옴표로 감싸야 합니다. |

quarto.yml에서 Twitter Card 메타데이터를 지정하는 더 완전한 예시는 다음과 같습니다:

website:
  twitter-card:
    creator: "@dragonstyle"
    site: "@rstudio"

Quarto는 website: twitter-card의 전역 메타데이터와 문서 내부의 twitter-card 메타데이터를 자동으로 병합합니다. 이는 site 같은 전역 옵션과 title/image 같은 문서별 옵션을 함께 지정해야 할 때 유용합니다.

Open Graph

Open Graph protocol은 웹에서 링크를 더 풍부하게 공유할 수 있도록 해주는 사양입니다. Slack, Discord, Facebook, Linkedin 등에서 링크 미리보기를 개선합니다. Open Graph 메타데이터 자동 생성을 활성화하려면 _quarto.yml에 다음을 추가합니다:

website:
  open-graph: true

이 경우 Quarto는 콘텐츠의 제목, 설명, 미리보기 이미지를 자동으로 생성합니다. 미리보기 이미지 선택 방식은 [Preview Images]를 참고하세요.

Open Graph 메타데이터에 사용할 추가 메타데이터도 지정할 수 있습니다:

Key Description
title 페이지 제목. Quarto는 페이지 메타데이터의 title을 자동으로 사용합니다. Open Graph 메타데이터에만 다른 제목을 쓰고 싶다면 open-graph 메타데이터에 title을 지정합니다. |
description 콘텐츠의 짧은 설명. Quarto는 페이지 메타데이터의 description을 자동으로 사용합니다. Open Graph 메타데이터에만 다른 설명을 쓰고 싶다면 open-graph 메타데이터에 description을 지정합니다. |
image

콘텐츠 미리보기 이미지 경로. 기본적으로 문서 메타데이터의 image 값을 사용하고, 없으면 website: 메타데이터의 image 값을 사용합니다. | 이미지를 제공하면 image-width와 image-height로 Twitter Card 모양을 개선할 수 있습니다. |

image가 제공되지 않으면 Quarto가 미리보기 이미지를 자동으로 찾습니다. 자세한 내용은 [Preview Images]를 참고하세요. |
locale Open Graph 메타데이터의 로케일. |
site-name 사이트 전체에 표시할 이름. open-graph 메타데이터에 명시하지 않으면 website:title 값을 사용합니다. |

quarto.yml에서 Open Graph 메타데이터를 지정하는 더 완전한 예시는 다음과 같습니다:

website:
  open-graph:
    locale: es_ES
    site-name: Quarto

Quarto는 website: open-graph의 전역 메타데이터와 문서 내부의 open-graph 메타데이터를 자동으로 병합합니다. 이는 site 같은 전역 옵션과 title/image 같은 문서별 옵션을 함께 지정해야 할 때 유용합니다.

미리보기 이미지

미리보기 이미지는 다음과 같은 방법으로 지정할 수 있습니다:

  1. 전체 URL: 적절한 메타데이터의 image 필드에 미리보기 이미지의 전체 URL을 지정합니다. 예:

    page.qmd
    title: "My Document"
image: "https://quarto.org/docs/websites/images/tools.png"

  2. 상대 경로: 문서 상대 경로(예: images/preview-code.png) 또는 프로젝트 상대 경로(예: /images/preview-code.png)를 지정할 수 있습니다. 이 경우 사이트 메타데이터에 site-url을 제공해야 합니다. 예:

    _quarto.yml
    website:
  site-url: "https://www.quarto.org"

    그리고 문서 프론트매터에서:

    page.qmd
    title: "My Document"
image: "/docs/websites/images/tools.png"

  3. 이미지 클래스: 페이지에 렌더링되는 이미지에 preview-image 클래스를 지정하면 미리보기 이미지로 사용할 수 있습니다. Quarto는 해당 클래스를 가진 첫 번째 이미지를 사용합니다. 예:

    ![](images/tools.png){.preview-image}

    이 클래스가 있는 이미지를 사용할 때도 사이트 메타데이터에 site-url이 필요합니다.

  4. 이미지 파일명: 위의 방법으로 미리보기 이미지를 지정하지 않으면, Quarto는 렌더링된 문서 안에서 다음 이름 중 하나를 가진 이미지를 찾아 사용합니다: preview.png, feature.png, cover.png, thumbnail.png.

어떤 방식으로도 미리보기 이미지가 지정되지 않은 페이지에 대해 기본값을 제공하려면 사이트 수준에서 지정합니다:

_quarto.yml
website:
  image: "https://quarto.org/quarto-dark-bg.jpeg"

미리보기 이미지 자동 탐색을 막고 싶다면 image를 false로 설정합니다:

page.qmd
---
image: false
---

Google Analytics

_quarto.yml에 google-analytics 키를 추가해 Google Analytics를 웹사이트에 추가할 수 있습니다. 가장 간단한 형태는 Google Analytics tracking Id(예: UA-xxxxxxx) 또는 Google Tag measurement Id(예: G-xxxxxxx)를 전달하는 것입니다:

website:
  google-analytics: "UA-XXXXXXXX"

Quarto는 키 자체를 사용해 적절한 방식(analytics.js 또는 gtag)으로 Google Analytics를 임베드합니다.

더 세밀한 제어를 위해 다음 키를 사용할 수 있습니다.

Key Description
tracking-id 웹사이트의 Google tracking Id 또는 measurement Id. |
storage

cookies - 쿠키를 사용해 사용자/세션 고유 식별 정보를 저장(기본값). |

none - 쿠키를 사용하지 않고 사용자/세션 식별 정보를 저장하지 않음. |

스토리지 옵션 선택에 대한 자세한 내용은 [Storage]를 참고하세요.
anonymize-ip 사용자 IP 주소 익명화. 자세한 내용은 Google Analytics IP Anonymization 참고. |
version 사용할 Google Analytics 버전. 현재 3(analytics.js) 또는 4(gtag) 지원. tracking-id에 따라 자동 감지되지만 직접 지정할 수 있습니다. |

스토리지

Google Analytics는 쿠키로 고유 사용자/세션을 구분합니다. 쿠키를 저장소로 사용한다면 [Cookie Consent]를 활성화해 사용자가 추적을 제어할 수 있도록 해야 할지 고려하세요.

storage를 none으로 설정하면 다음과 같은 효과가 있습니다:

  • Google Analytics v3(analytics.js)
    추적 쿠키를 사용하지 않습니다. 개별 페이지 조회는 정상적으로 추적되어 어떤 페이지가 얼마나 조회되는지 확인할 수 있습니다. 하지만 고유 사용자/세션 추적은 쿠키가 없으므로 올바르게 보고되지 않습니다.

  • Google Tags(gtag)
    광고/애널리틱스 추적 쿠키에 대한 사용자 동의가 보류됩니다. 이 모드에서는 사용자 식별 정보 없이 데이터가 수집되지만, 현재 Google Analytics 보고서에는 표시되지 않습니다.

쿠키 동의

Quarto는 쿠키를 설정하는 스크립트 실행 전에 쿠키 동의를 요청할 수 있는 Cookie Consent 기능을 제공합니다.

사용자의 쿠키 선호도는 Google Analytics를 자동으로 제어하며, 추가한 사용자 정의 스크립트에도 적용할 수 있습니다([Custom Scripts and Cookie Consent] 참고). 기본 쿠키 동의 요청을 활성화하려면 다음을 사용합니다:

website:
  cookie-consent: true

동의 화면의 모양과 동작을 다음 옵션으로 더 사용자 정의할 수 있습니다:

Key Description
type

요청할 동의 유형. 다음 중 하나: |

implied - (기본값) 쿠키 사용을 알리고 선호도 변경을 허용하지만, 사용자가 변경하지 않는 한 쿠키를 차단하지 않습니다. |

express - 사용자가 명시적으로 동의할 때까지 쿠키를 차단합니다(동의하지 않으면 계속 차단). |
style

동의 배너 스타일: |

simple - (기본값) 웹사이트 오른쪽 하단의 간단한 다이얼로그. |

headline - 웹사이트 상단 전체 너비 배너. |

interstitial - 웹사이트 전체에 반투명 오버레이. |

standalone - 웹사이트 전체를 덮는 불투명 오버레이. |
palette

동의 배너의 다크/라이트 모드: |

light - 밝은 배너. |

dark - 어두운 배너. |
language 쿠키 동의 프롬프트에 사용할 언어(IETF 언어 태그). | 지정하지 않으면 문서 언어를 사용합니다. |
policy-url 사이트의 쿠키/프라이버시 정책 URL. |
prefs-text 웹사이트 푸터에 표시할 쿠키 선호도 링크 텍스트. |

커스텀 예시는 다음과 같습니다:

website:
  cookie-consent:
    type: express
    style: headline
    palette: dark
  google-analytics:
    tracking-id: "G-XXXXXXX"
    anonymize-ip: true

쿠키 선호도

새 사용자가 사이트를 방문할 때 동의를 요청하는 것 외에도, Cookie Consent는 웹사이트 푸터에 쿠키 선호도 링크를 추가합니다. prefs-text로 링크 텍스트를 제어할 수 있습니다. 이 링크를 직접 배치하고 싶다면 #open_preferences_center id를 가진 링크를 사이트에 추가하면 Cookie Consent가 푸터에 링크를 추가하지 않습니다. 예:

Change [cookie preferences]{#open_preferences_center}

사용자 정의 스크립트와 쿠키 동의

Cookie Consent는 사용자가 동의하기 전에는 스크립트 실행을 막습니다. 사용자 정의 스크립트를 Cookie Consent로 제어하려면:

  1. 스크립트 태그를 type='text/plain'으로 넣습니다(사용자가 동의하면 type이 text/javascript로 바뀌고 스크립트가 실행됨).

  1. 스크립트 태그에 cookie-consent 속성을 추가하고 다음 4단계 중 하나로 설정합니다:

    Level Description
    strictly-necessary 반드시 필요한 스크립트로 자동 로드되며 사용자가 비활성화할 수 없습니다. |
    functionality 기본 기능에 필요한 스크립트(예: 사용자 언어 선호도 기억). |
    tracking 사용자 추적에 사용하는 스크립트(예: Google Analytics). |
    targeting 광고 타게팅 목적의 스크립트(예: Google AdSense 리마케팅). |

사용자 추적에 사용하는 스크립트 예시는 다음과 같습니다:

<script type="text/plain" cookie-consent="tracking">

// My tracking JS code here

</script>

사이트 리소스

입력/설정 파일 외에도 사이트에는 다양한 리소스(예: 이미지)가 포함될 수 있으며, 이를 사이트와 함께 배포해야 합니다. Quarto는 사이트 내에서 참조된 모든 파일을 자동으로 감지해 출력 디렉터리(예: _site)로 복사합니다.

Quarto는 다음 파일도 인식해 출력 디렉터리로 복사합니다:

  • 404.html - 404 페이지를 제공하는 한 방법
  • robots.txt - Robots Exclusion Protocol에서 정의한 파일로, 검색 엔진 크롤러가 접근할 수 있는/없는 페이지를 지정
  • _redirects - 일부 배포 제공자가 페이지 리디렉션을 제공할 때 사용하는 파일(예: Netlify)
  • CNAME - 일부 배포 제공자가 커스텀 도메인을 지정할 때 사용하는 파일(예: GitHub Pages)
  • .nojekyll - GitHub Pages가 Jekyll 빌드를 건너뛰도록 하는 파일(예: docs/에서 배포)

자동 감지가 실패하거나 사이트에서 명시적으로 링크되지 않은 파일을 배포하려면 설정에 resources 항목을 추가할 수 있습니다. 예를 들어 프로젝트 디렉터리 내 모든 Excel 스프레드시트를 포함하려면:

project:
  type: website
  resources: 
    - "*.xlsx"

YAML은 영숫자가 아닌 문자로 시작하는 문자열을 따옴표로 감싸야 하므로 *.xlsx를 따옴표로 감쌌습니다.

개별 파일에도 resources 메타데이터 값을 추가할 수 있습니다. 예:

title: "My Page"
resources:
  - "sheet.xlsx"

이미지는 가장 일반적으로 사용되는 리소스 유형입니다. 사이트 여러 페이지에서 참조할 전역 이미지를 가지고 있다면 사이트 절대 경로로 참조하면 배포 시 자동으로 상대 경로로 변환됩니다. 예:

![](/images/logo.png)

다크 모드

Quarto 웹사이트는 라이트/다크 모드를 모두 지원할 수 있습니다. 예를 들어 flatly와 darkly 테마를(라이트/다크 쌍으로 설계됨) 다음과 같이 사용할 수 있습니다:

theme:
  light: flatly
  dark: darkly

다크/라이트 테마 선택에 대한 자세한 내용은 Dark Mode를 참고하세요.

Light Dark
라이트 테마의 Quarto 사이드바. 'Dark mode' 토글이 꺼져 있습니다. | 다크 테마의 Quarto 사이드바. 'Dark mode' 토글이 켜져 있습니다. |

활성화되면 사용자가 웹사이트 모양을 제어할 수 있는 토글이 표시됩니다. 토글은 다음과 같이 내비게이션에 자동 추가됩니다:

  1. 내비게이션 바가 있으면 토글이 바 오른쪽 상단에 표시됩니다.
  2. 내비게이션 바가 없고 사이드바가 있으면, 사이드바 도구가 표시되는 위치(사이드바 제목/로고 옆)에 표시됩니다.
  3. 내비게이션 바와 사이드바가 모두 없으면 토글이 페이지 오른쪽 상단에 표시됩니다.