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
---

Preview

Specify options that control the behavior of quarto preview within the preview key. For example:

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

Available preview options include:

Serve

If you are creating a project extension for another publishing system that includes its own preview server (for example, Hugo or Docusaurus) then use the preview: serve options to customize the behavior of the preview server.

See the Hugo and Docusaurus extension source code for example usages of preview: serve.

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
---

Nav Items

Nav items appear in the left or right key of navbar definitions, or contents key of sidebar definitions. For example:

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

Note that the icon option is available for items in the Navbar, however items in the Sidebar do not support the icon option.

Sidebar

Options that define the side navigation area for a website. For example:

---
website:
  sidebar:
    search: true
---

Footer

Website page footer definition. For example:

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

Search

Search options are specified under the search key of website. For example:

---
website:
  search:
    location: navbar
    type: overlay
---

Algolia Options

You can use an Algolia index as the back end of website search. Specify Algolia options using the algolia sub-key of search, for example:

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

The index-fields option provides sub-fields within the Algolia index to target for searches:

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

Open Graph

Comments

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

Hypothesis

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

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

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
---

Giscus

Enable and configure usage of the Giscus app via the comments key. For example:

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

Listings

Listings enable you to automatically generate the contents of a page (or region of a page) from a list of Quarto documents or other custom data. You can enable listings on a page using the listing option in the document front matter, for example:

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

Feed

Enable an RSS feed for your listing by including the feed option.

About

Layout a simple about page for an individual or organization. For more, see the About Pages documentation.