Website 옵션

website 프로젝트에서 사용 가능한 모든 옵션을 아래에 정리했습니다. Quarto로 웹사이트를 만드는 자세한 안내는 웹사이트 만들기를 참고하세요.

프로젝트

프로젝트의 유형, 렌더링 대상, 출력 등을 정의하는 옵션입니다. 프로젝트 옵션은 project 키 아래에 지정합니다. 예:

_quarto.yml

project:
  type: website
  output-dir: _site

`title`	프로젝트 제목
`type`	프로젝트 유형(`default`, `website`, `book`, `manuscript`)
`render`	렌더링할 파일 목록(기본 전체)
`execute-dir`	계산 작업 디렉터리 제어(`file`: 현재 파일 디렉터리, `project`: 프로젝트 루트)
`output-dir`	출력 디렉터리
`lib-dir`	HTML 라이브러리(JS/CSS 등) 디렉터리
`resources`	출력에 복사할 추가 파일
`brand`	brand.yml 경로 또는 밝기/어두움별 brand.yml 객체
`preview`	`quarto preview` 옵션(Preview 참조)
`pre-render`	사전 렌더 단계에서 실행할 스크립트
`post-render`	사후 렌더 단계에서 실행할 스크립트

미리보기

preview 키에서 quarto preview의 동작을 제어하는 옵션을 지정합니다. 예:

_quarto.yml

project:
  type: website
  output-dir: _site
  preview:
    port: 4200
    browser: false

사용 가능한 preview 옵션은 다음과 같습니다.

`port`	리스닝 포트(기본 3000~8000 사이 랜덤)
`host`	바인딩 호스트 이름(기본 127.0.0.1)
`serve`	외부 프리뷰 서버 옵션(Serve 참조)
`browser`	프리뷰 보기 브라우저 자동 열기(기본 true)
`watch-inputs`	입력 파일 변경 시 재렌더(기본 true)
`navigate`	출력이 업데이트되면 브라우저 자동 이동(기본 true)
`timeout`	활성 클라이언트 없을 때 종료까지 대기 시간(초)

Serve

자체 미리보기 서버가 포함된 다른 배포 시스템(예: Hugo, Docusaurus)용 프로젝트 확장을 만들고 있다면, preview: serve 옵션으로 미리보기 서버 동작을 사용자 지정하세요.

_quarto.yml

project:
  type: website
    preview:
      serve:
        cmd: "hugo serve --port {port} --bind {host} --navigateToChanged"
        env:
          HUGO_RELATIVEURLS: "true"
        ready: "Web Server is available at"

`cmd`	지정 명령으로 프로젝트 프리뷰 실행(`{port}`로 포트 삽입)
`args`	프리뷰 명령에 추가할 커맨드라인 인수
`env`	프리뷰 명령 환경 변수
`ready`	서버 준비 감지용 정규 표현식

preview: serve 사용 예시는 Hugo와 Docusaurus 확장 소스 코드를 참고하세요.

Website

website 출력에 영향을 주는 옵션입니다. Website 옵션은 website 키 아래에 지정합니다. 예:

_quarto.yml

website:
  title: "My Website"
  image: opengraph.png
  page-navigation: true

`title`	웹사이트 제목
`description`	웹사이트 설명
`favicon`	파비콘 경로
`site-url`	배포된 웹사이트 기본 URL
`site-path`	사이트 경로(기본 `/`; `site-url` 설정 시 불필요)
`repo-url`	웹사이트 소스 코드 저장소 기본 URL
`repo-link-target`	저장소 링크 target 값
`repo-link-rel`	저장소 링크 rel 값
`repo-subdir`	웹사이트가 포함된 저장소 하위 디렉터리
`repo-branch`	웹사이트 소스 브랜치(기본 `main`)
`issue-url`	이슈 신고 리포지토리 URL
`repo-actions`	저장소 액션 링크 목록(`none` 또는 `edit`, `source`, `issue` 등)
`reader-mode`	사이드바와 목차 숨김 기능을 제공하는 reader-mode 도구 표시
`google-analytics`	사이트에 Google Analytics 활성화
`announcement`	페이지 상단 공지(Announcement 참조)
`cookie-consent`	쿠키 동의 요청 기능 (https://www.cookieconsent.com/ 참고; Google Analytics 및 사용자 스크립트 제어 가능)
`search`	사이트 검색 활성화/비활성화 또는 커스텀 Search Options
`navbar`	네비게이션 바 옵션(Navbar 참조)
`sidebar`	사이드바 옵션(Sidebar 참조)
`body-header`	본문 시작(title/author 아래) 삽입 Markdown
`body-footer`	본문 아래에 삽입할 Markdown
`margin-header`	여백 콘텐츠 상단 Markdown
`margin-footer`	여백 콘텐츠 하단 Markdown
`page-navigation`	하단에 이전/다음 글 링크 제공
`back-to-top-navigation`	상단으로 이동 버튼 제공
`bread-crumbs`	2단계 이상 페이지에 네비게이션 브레드크럼 표시 여부
`page-footer`	페이지 하단(텍스트 또는 page footer 정의)
`image`	`twitter`/`open-graph` 기본 썸네일 이미지
`image-alt`	`twitter`/`open-graph` 기본 썸네일 대체 텍스트
`comments`
`open-graph`	Open Graph 메타데이터 생성(Open Graph)
`twitter-card`	Twitter Card 메타데이터 생성(Twitter Card)
`other-links`	목차 아래에 표시할 기타 링크 목록
`code-links`	문서와 함께 표시할 코드 링크 목록
`drafts`	임시 처리할 입력 문서 목록(Website Drafts 참고)
`draft-mode`	임시 문서 처리 방식(`visible`: 표시, `unlinked`: 렌더되나 네비게이션/검색/목록 제외, `gone`: 내용을 비워 링크 없음 기본)

내비게이션 바

website의 상단 내비게이션 바를 정의하는 옵션입니다. 예:

_quarto.yml

website:
  navbar:
    search: true

`title`	네비게이션 바 제목 (지정되지 않으면 프로젝트 제목 사용)
`logo`	제목 왼쪽에 표시할 이미지 사양
`logo-alt`	로고 이미지 대체 텍스트
`logo-href`	네비게이션 바 로고/제목의 링크 대상(href) — 기본값은 사이트 루트(/index.html)
`background`	네비게이션 바 배경색(이름 또는 16진수)
`foreground`	네비게이션 바 전경색(이름 또는 16진수)
`search`	네비게이션 바 내 검색창 포함
`pinned`	항상 표시되는 고정된 네비게이션 바
`collapse`	화면이 좁아질 때 메뉴로 축소
`collapse-below`	네비게이션 바가 메뉴로 축소되는 반응형 브레이크포인트(`sm`, `md`, `lg` 기본, `xl`, `xxl`)
`left`	네비게이션 바 왼쪽 항목 목록(Nav Items 참조)
`right`	네비게이션 바 오른쪽 항목 목록(Nav Items 참조)
`toggle-position`	반응형 모드에서 축소된 바 토글 위치
`tools-collapse`	도구를 화면이 좁을 때 메뉴로 축소

Nav 항목

Nav 항목은 navbar 정의의 left 또는 right 키, 또는 sidebar 정의의 contents 키에 나타납니다. 예:

_quarto.yml

website:
  navbar:
    right:
      - icon: github
        href: https://github.com/
        aria-label: GitHub

`aria-label`	접근성을 위한 항목 레이블
`href`	프로젝트 내 파일 또는 외부 URL 링크
`icon`	Bootstrap 아이콘 이름(예: `github`, `twitter`, `share`; https://icons.getbootstrap.com/ 참조)
`menu`	하위 메뉴 항목 목록(navigation items 참조)
`text`	항목 표시 텍스트(미설정 시 문서 제목 사용)
`rel`	rel 속성 값(공백 구분 복수 값 허용; https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel 참조)
`target`	target 속성 값(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target 참조)

icon 옵션은 내비게이션 바 항목에서 사용할 수 있지만, 사이드바 항목은 icon 옵션을 지원하지 않습니다.

사이드바

website의 측면 내비게이션 영역을 정의하는 옵션입니다. 예:

_quarto.yml

website:
  sidebar:
    search: true

`id`	사이드바 식별자
`title`	사이드바 제목(미설정 시 프로젝트 제목 사용)
`logo`	사이드바에 표시할 로고 이미지 지정
`logo-alt`	로고 이미지 대체 텍스트
`logo-href`	로고/제목 링크(href; 기본 사이트 루트)
`search`	사이드바 내 검색 컨트롤 포함
`tools`	사이드바 도구 목록(Sidebar Tools 참조)
`contents`	사이드바에 표시할 네비게이션 항목 목록 및 섹션 서브리스트
`style`	사이드바 스타일(`docked` 또는 `floating`)
`background`	사이드바 배경색(이름 또는 16진수)
`foreground`	사이드바 전경색(이름 또는 16진수)
`border`	사이드바 테두리 표시 여부(`docked` 기본 true)
`alignment`	사이드바 내 항목 정렬(`left`, `right`, `center`)
`collapse-level`	기본적으로 접을 사이드바 깊이
`pinned`	접은 상태일 때 상단에 고정
`header`	사이드바 상단에 넣을 Markdown(텍스트 또는 파일 경로)
`footer`	사이드바 하단에 넣을 Markdown(텍스트 또는 파일 경로)

사이드바 도구

사이드바에 표시되는 동작 버튼입니다. 예:

_quarto.yml

website:
  sidebar:
    tools:
      - icon: github
        href: https://github.com/

`icon`	Bootstrap 아이콘 이름(예: `github`, `twitter`, `share`; https://icons.getbootstrap.com/ 참고)
`href`	프로젝트 내 파일 또는 외부 URL 링크
`menu`	하위 메뉴 항목(navigation items 참조)

공지

사이트 상단에 표시되는 공지입니다. 예:

---
website:
  announcement: 
    content: "**New** - this is an announcement" 
    position: below-navbar 
---

`content`	공지 내용
`dismissable`	사용자가 닫을 수 있는 공지 여부
`icon`	공지에 사용할 Bootstrap 아이콘 이름(예: `github`, `twitter`, `share`; https://icons.getbootstrap.com/ 참조)
`position`	공지 위치(`above-navbar` 기본 또는 `below-navbar`)
`type`	공지 유형(`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`), 외관에 영향

푸터

Website 페이지의 푸터 정의입니다. 예:

_quarto.yml

website:
  page-footer:
    center: 
      - text: "About"
        href: about.qmd
      - text: "License"
        href: license.md
      - text: "Trademark"
        href: trademark.qmd

`left`	페이지 하단 왼쪽 내용
`right`	페이지 하단 오른쪽 내용
`center`	페이지 하단 가운데 내용
`border`	하단 테두리 설정(`true`/`false` 또는 색상)
`background`	하단 배경색
`foreground`	하단 전경색

검색

검색 옵션은 website의 search 키 아래에 지정합니다. 예:

_quarto.yml

website:
  search:
    location: navbar
    type: overlay

`location`	검색 위젯 위치(`navbar` 또는 `sidebar`)
`type`	검색 UI 유형(`overlay` 또는 `textbox`)
`limit`	표시할 일치 항목 수(기본 20)
`collapse-after`	추가 결과를 축소할 일치 항목 기준
`copy-button`	검색 링크 복사 버튼 제공 여부
`merge-navbar-crumbs`	false면 `search.json` 크럼과 navbar 크럼을 병합하지 않음
`keyboard-shortcut`	단일 문자 검색 단축키 목록
`show-item-context`	검색 결과 항목 표시 시 상위 항목 포함 여부
`algolia`	Algolia 인덱스를 사이트 검색에 사용(Algolia Options 참조)

Algolia 옵션

Algolia 인덱스를 website 검색의 백엔드로 사용할 수 있습니다. search의 algolia 하위 키로 Algolia 옵션을 지정합니다. 예:

_quarto.yml

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>

`index-name`	검색 시 사용할 Algolia 인덱스 이름
`application-id`	Algolia 애플리케이션 고유 ID
`search-only-api-key`	Algolia 연결용 Search-Only API 키
`analytics-events`	Algolia 분석 이벤트 추적 활성화
`show-logo`	검색 결과 바닥글에 Algolia 로고 표시 여부
`index-fields`	검색 대상 필드 목록(자세한 내용은 아래 참조)
`params`	검색 실행 시 전달할 추가 파라미터

index-fields 옵션은 검색 대상이 되는 Algolia 인덱스의 하위 필드를 제공합니다.

`href`	색인 항목 URL을 담는 필드
`title`	색인 항목 제목을 담는 필드
`text`	색인 항목 텍스트를 담는 필드
`section`	색인 항목 섹션을 담는 필드

소셜

소셜 메타데이터는 website 옵션의 하위 키로 제공합니다. true를 지정해 기본 옵션으로 소셜 메타데이터를 생성하거나, 아래에 나열된 Twitter 또는 Open Graph 옵션을 하나 이상 지정할 수 있습니다. 예:

_quarto.yml

website:
  open-graph: true
  twitter-card: 
    site: "@sitehandle"

Twitter 카드

twitter-card 키 아래에 Twitter 옵션을 지정하세요.

_quarto.yml

website:
  twitter-card: 
    site: "@sitehandle"

`title`	페이지 제목(기본은 메타 제목; 재지정 가능)
`description`	콘텐츠 설명(기본은 메타 설명; 재지정 가능)
`image`	미리보기 이미지 경로(기본은 포맷 메타 이미지; 너비/높이 지정 가능)
`image-alt`	미리보기 이미지 대체 텍스트(기본은 포맷 메타)
`image-width`	이미지 너비(픽셀)
`image-height`	이미지 높이(픽셀)
`card-style`	카드 스타일(`summary` 또는 `summary_large_image`; 미지정 시 자동 선택)
`creator`	콘텐츠 제작자 Twitter `@username`
`site`	사이트 Twitter `@username`

Open Graph

open-graph 키 아래에 Open Graph 옵션을 지정하세요.

_quarto.yml

website:
  open-graph: 
    title: "Title for Open Graph"

`title`	페이지 제목(기본적으로 페이지 메타 제목 사용; 재지정 가능)
`description`	콘텐츠 요약 설명(기본 설명 대신 재정의할 수 있음)
`image`	미리보기 이미지 경로(기본은 메타 이미지; `image-width`/`image-height`도 지정 가능)
`image-alt`	미리보기 이미지 대체 텍스트(기본은 메타 값; 폭/높이 지정 가능)
`image-width`	이미지 너비(픽셀)
`image-height`	이미지 높이(픽셀)
`locale`	Open Graph 메타데이터 로케일
`site-name`	전체 사이트 표시 이름(미설정 시 사이트/도서 제목 사용)

Hypothesis, Utterances, Giscus를 사용해 website에 댓글 기능을 추가할 수 있습니다.

Hypothesis

comments 키로 Hypothesis 댓글을 활성화하고 구성합니다. 예:

_quarto.yml

website:
  comments: 
    hypothesis:
      theme: clean
      openSidebar: false

`client-url`	커스텀 Hypothesis 클라이언트 URL
`openSidebar`	시작 시 사이드바 자동 열림 여부
`showHighlights`	文서 내 하이라이트 기본 표시 방식(`always`, `whenSidebarOpen`, `never`)
`theme`	사이드바 전체 테마(`classic`, `clean`)
`enableExperimentalNewNoteButton`	실험적 새 노트 버튼을 노트 탭에 표시할지 여부
`usernameUrl`	주석 작성자 링크 클릭 시 새 탭으로 열 URL
`services`	서비스 정의 배열
`branding`	UI에 적용할 커스텀 브랜딩/색상
`externalContainerSelector`	사이드바 iframe을 넣을 외부 요소 CSS 셀렉터
`focus`	페이지 주석에 대한 사용자 중심 필터 셋
`requestConfigFromFrame`	설정 요청 대상 호스트 iframe 지정
`assetRoot`	자산 로드용 루트 URL
`sidebarAppUrl`	주석 표시 사이드바 앱 URL

위에 나열된 Hypothesis 옵션에 대한 추가 문서는 Hypothesis Publisher Config를 참고하세요.

Utterances

comments 키로 Utterances 댓글을 활성화하고 구성합니다. 예:

_quarto.yml

website:
  comments: 
    utterances:
      repo: quarto-dev/quarto-web

`repo`	댓글을 저장할 Github 저장소
`label`	Utterances가 생성한 이슈에 붙일 레이블
`theme`	Utterances에 사용할 Github 테마(예: github-light, github-dark 등)
`issue-term`	배포물을 Github 이슈로 매핑하는 방식(`pathname`, `url`, `title`, `og:title`)

Giscus

comments 키로 Giscus 앱 사용을 활성화하고 구성합니다. 예:

_quarto.yml

website:
  comments:
    giscus:
      repo: quarto-dev/quarto-web

`repo`	코멘트를 저장할 GitHub 저장소입니다. 정상 작동하려면 저장소가 공개여야 하며 giscus 앱이 설치되어 있고 토론 기능이 활성화되어야 합니다.
`repo-id`	GitHub 저장소 식별자입니다. https://giscus.app 구성 도구에서 빠르게 확인할 수 있습니다. 제공하지 않으면 Quarto가 렌더링 시점에 자동으로 찾아봅니다.
`category`	새 토론을 만들 토론 카테고리입니다. 신규 토론을 유지 관리자와 giscus만 생성할 수 있도록 Announcements 유형 카테고리를 사용하는 것이 권장됩니다.
`category-id`	GitHub 카테고리 식별자입니다. https://giscus.app 구성 도구에서 빠르게 확인할 수 있습니다. 제공하지 않으면 Quarto가 렌더링 시점에 자동으로 찾아봅니다.
`mapping`	페이지와 임베드된 토론 사이의 매핑입니다. `pathname`: 토론 제목에 페이지 경로가 포함됩니다. `url`: 토론 제목에 페이지 URL이 포함됩니다. `title`: 토론 제목에 페이지 제목이 포함됩니다. `og:title`: 토론 제목에 `og:title` 메타데이터 값이 포함됩니다. 기타 문자열이나 숫자: 다른 문자열은 그대로 전달되며 해당 값을 포함하는 토론 제목이 사용됩니다. 숫자는 토론 번호로 처리되어 자동 토론 생성은 지원되지 않습니다.
`reactions-enabled`	댓글보다 앞서 토론 메인 배포물에 대한 반응을 표시합니다.
`loading`	`loading: lazy`를 지정하면 사용자가 댓글 컨테이너 근처로 스크롤할 때까지 댓글 로드를 지연합니다.
`input-position`	댓글 입력 상자를 댓글 위나 아래에 배치합니다.
`theme`	댓글을 표시할 때 사용할 giscus 테마입니다. 밝은 테마와 어두운 테마를 모두 지원합니다. 하나의 테마 이름만 제공하면 밝거나 어두운 테마 모두 해당 이름이 사용됩니다. 서로 다른 테마를 지정하려면 `light`/`dark` 키를 사용하세요: `website: comments: giscus: theme: light: light # 밝은 웹사이트 테마에 적용할 giscus 테마 dark: dark_dimmed # 어두운 웹사이트 테마에 적용할 giscus 테마`
`language`	댓글 인터페이스를 표시할 때 사용할 언어입니다.

목록은 Quarto 문서 목록이나 기타 사용자 정의 데이터로 페이지(또는 페이지의 일부) 내용을 자동 생성합니다. 문서 프론트매터의 listing 옵션으로 목록을 활성화할 수 있습니다. 예를 들어 listing: default를 설정하면 현재 문서를 제외한 디렉터리의 모든 문서를 목록으로 생성합니다.

---
title: "Listing Example"
listing: default
---

목록을 사용자 지정하려면 listing 키 아래에 추가 옵션을 지정하세요.

---
title: "Listing Example"
listing: 
  contents: posts
  type: grid
  grid-columns: 2
---

`id`	목록 ID 및 `div` 대상 처리
`type`	생성할 목록 유형(`default`, `table`, `grid`, `custom`)
`contents`	목록에 포함할 문서/야믈 파일 경로 또는 glob
`sort`	정렬 필드 및 방향(`date asc` 등; `sort:false` 지정 시 원본 순서)
`max-items`	최대 항목 수
`page-size`	페이지당 항목 수
`sort-ui`	정렬 컨트롤 표시 여부(표시 필드 목록 제공 가능)
`filter-ui`	필터링 컨트롤 표시 여부 및 필드 목록
`categories`	페이지 여백에 카테고리 표시(`numbered`, `unnumbered`, `cloud`)
`feed`	목록 항목으로 RSS 피드 생성(Feed 참조)
`date-format`	날짜 표시 형식(예: d-M-yyy; https://deno.land/std@0.125.0/datetime 참고)
`max-description-length`	표시 설명 최대 문자 수(기본 175)
`image-placeholder`	이미지 없을 때 사용할 기본 이미지
`image-lazy-loading`	false면 즉시 로드, true면 뷰포트 진입 시 로드
`image-align`	`default` 목록에서 이미지 위치(`left` 또는 `right`)
`image-height`	이미지 높이(CSS 문자열; 너비 자동, 자르기 포함)
`grid-columns`	그리드 목록 열 수(기본 3)
`grid-item-border`	그리드 항목 카드 테두리 표시 여부(기본 true)
`grid-item-align`	그리드 항목 내용 정렬(`left`, `right`, `center`)
`table-striped`	테이블 목록 줄 무늬 배경 표시 여부(기본 false)
`table-hover`	테이블 목록에서 마우스 오버 시 행 강조(기본 false)
`template`	사용자 정의 목록 템플릿 경로
`template-params`	사용자 템플릿에 전달할 파라미터
`fields`	목록에 포함할 필드 목록
`field-display-names`	특정 필드의 표시명 매핑
`field-types`	필드 데이터 타입 지정(`date`, `number`; 미지정 시 문자열)
`field-links`	테이블 유형에서 링크로 표시할 필드 목록(기본 `title` 또는 `filename`)
`field-required`	필수 필드 목록(없으면 렌더 오류)
`include`	일치하는 필드 값을 가진 항목 포함
`exclude`	일치하는 필드 값을 가진 항목 제외

피드

feed 옵션을 포함해 목록의 RSS 피드를 활성화할 수 있습니다.

---
title: "Listing Example"
listing:
  contents: posts
  feed:
    items: 10
---

`items`	피드에 포함할 항목 수(기본값 20)
`type`	피드에 포함할 콘텐츠 유형 `full` (기본값): 문서 전체 콘텐츠 포함 `partial`: 문서 첫 문단만 포함 `metadata`: 제목/설명 등 메타데이터만 포함
`title`	피드 제목(지정되지 않으면 Quarto 프로젝트 사이트 제목)
`image`	피드용 이미지 경로(미지정 시 목록 페이지 또는 프로젝트 사이트 이미지 사용)
`description`	피드 설명(미지정 시 목록 페이지 또는 프로젝트 사이트 설명 사용)
`language`	피드 언어(미지정 시 생략; 유효 언어 코드 목록은 https://www.rssboard.org/rss-language-codes 참고)
`categories`	각 카테고리별 RSS 피드를 생성할 카테고리 목록
`xml-stylesheet`	RSS 피드 스타일링에 사용할 XML 스타일시트(XSL) 경로

About

개인 또는 조직의 간단한 소개 페이지를 레이아웃합니다. 문서 프론트매터의 about 키 아래에 소개 페이지 옵션을 지정하세요.

---
title: About
about:
  template: jolla
  image: profile.jpg
  links:
    - icon: twitter
      text: twitter
      href: https://twitter.com
---

자세한 내용은 About 페이지 문서를 참고하세요.

`id`	about 페이지 대상 ID. 해당 ID를 가진 `div` 내용을 선택한 템플릿에 삽입하고, 없으면 생성하여 페이지 끝에 추가합니다.
`template`	about 페이지 레이아웃 템플릿 목록(`jolla`, `trestles`, `solana`, `marquee`, `broadside`).
`image`	about 페이지 메인 이미지 경로(미지정 시 문서 지정 `image` 사용).
`image-alt`	about 페이지 메인 이미지 대체 텍스트.
`image-title`	about 페이지 메인 이미지 제목.
`image-width`	about 페이지 이미지 유효 CSS 너비.
`image-shape`	about 페이지 이미지 형태(`rectangle`, `round`, `rounded`).
`links`	about 페이지에 표시할 링크 목록(navigation items 참조).