Website Options

All available options for website projects are documented below. See Creating a Website for an in-depth guide to creating websites with Quarto.

Project

Options that define the type, render targets, and output of a project. Project options are specified under the project key. For example:

---
project:
  type: website
  output-dir: _site
---
type

Project type (default, website, or book)

render

Files to render (defaults to all files)

execute-dir

Working directory for computations: file uses the directory of the currently executing file, project uses the root project directory.

output-dir

Output directory

lib-dir

HTML library (JS/CSS/etc.) directory

resources

Additional file resources to be copied to output directory

Website

Options that affect website output. Website options are specified under the website key. For example:

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

Website title

site-url

Base URL for published website

site-path

Path to site (defaults to ‘/’). Not required if you specify site-url.

repo-url

Base URL for website source code repository

repo-branch

Branch of website source code (defaults to main)

repo-actions

Links to source repository actions (none or one or more of edit, source, issue)

search

Site search (true or false to enable/disable, or provide custom Search Options

navbar

Navbar options (see Navbar)

sidebar

Sidebar options (see Sidebar)

margin-header

Markdown to place above margin content (text or file path)

margin-footer

Markdown to place below margin content (text or file path)

page-navigation

Provide next and previous article links in footer

page-footer

Page footer. Text content or page footer definition.

image

Default site thumbnail image for twitter /open-graph

comments
open-graph

Generate Open Graph metadata (see Open Graph options)

twitter-card

Generate Twitter Card metadata (see Twitter Card options)

Social

Social metadata is provided as a subkey of website options. You can specify true to generate social metadata using a set of default option, or specify one or more Twitter or Open Graph specific options as enumerated below. For example:

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

Twitter Card

title

The title of the page. Note that by default Quarto will automatically use the title metadata from the page. Specify this field if you’d like to override the title for this provider.

description

A short description of the content. Note that by default Quarto will automatically use the description metadata from the page. Specify this field if you’d like to override the description for this provider.

image

The path to a preview image for the content. By default, Quarto will use the image value from the website or book metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-width

Image width (pixels)

image-height

Image height (pixels)

card-style

Card style (summary or summary_large_image). If this is not provided, the best style will automatically selected based upon other metadata. You can learn more about Twitter Card styles here.

creator

@username of the content creator (must be a quoted string)

site

@username of the website (must be a quoted string)

Open Graph

title

The title of the page. Note that by default Quarto will automatically use the title metadata from the page. Specify this field if you’d like to override the title for this provider.

description

A short description of the content. Note that by default Quarto will automatically use the description metadata from the page. Specify this field if you’d like to override the description for this provider.

image

The path to a preview image for the content. By default, Quarto will use the image value from the website or book metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-width

Image width (pixels)

image-height

Image height (pixels)

locale

Locale of open graph metadata

site-name

Name that should be displayed for the overall site. If not explicitly provided in the open-graph metadata, Quarto will use the website or book title by default.

Comments

You can add commenting to your website using either Hypothesis or Utterances.

Hypothesis

Enable and configure Hypothesis commenting via comments key. For example:

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

Controls whether the sidebar opens automatically on startup.

showHighlights

Controls whether the in-document highlights are shown by default (always or never)

theme

Controls the overall look of the sidebar (classic or clean)

enableExperimentalNewNoteButton

Controls whether the experimental New Note button should be shown in the notes tab in the sidebar.

usernameUrl

Specify a URL to direct a user to, in a new tab. when they click on the annotation author link in the header of an annotation.

services

Array of service definitions

branding

Custom branding/colors to apply to UI

externalContainerSelector

A CSS selector specifying the containing element into which the sidebar iframe will be placed.

focus

User focused filter set for the available annotations on a page

requestConfigFromFrame

Speicfy a host iframe to request configuration from

assetRoot

The root URL from which assets are loaded.

sidebarAppUrl

The URL for the sidebar application which displays annotations.

For additional documentation on the Hypothesis options enumerated above, see the Hypothesis Publisher Config documentation.

Utterances

Enable and configure Utterances commenting via the comments key. For example:

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

The Github repo that will be used to store comments.

label

The label that will be assigned to issues created by Utterances.

theme

The Github theme that should be used for Utterances (github-light, github-dark, github-dark-orange, icy-dark, dark-blue, photon-dark, body-light, or gruvbox-dark)