Website Tools

Headers & Footers

You can provide standard headers and footers for pages on your site. These can apply to the main document body or to the sidebar. Available options include:

Value Description
body-header Markdown to insert at the beginning of each page’s body (below the title and author block).
body-footer Markdown to insert below each page’s body.
margin-header Markdown to insert above right margin content (i.e. table of contents).
margin-footer Markdown to insert below right margin content.

For example (included in _quarto.yml) :

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

Note that links to figures should start with a / to work on each level of the website.

Social Metadata

You can enhance your website and the content that you publish to it by including additional types of metadata, including:

  • Favicon
  • Twitter Cards
  • Open Graph

One important thing to note about using website tools is that while these tools are added to websites within the website key, in a book you should include the same options in the book key. For example, in a website you would include a favicon and twitter card as follows:

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

In a book you’d use the book key instead:

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

As you read the documentation below, keep in mind to substitute book for website if you are authoring a book.

Favicon

The favicon for your site provides an icon for browser tabs and other sites that link to yours. Use the favicon option to provide the path to a favicon image. For example:

website:
  favicon: logo.png

Twitter Cards

Twitter Cards provide an enhanced appearance when someone links to your site on Twitter. When a link to your site is included in a Tweet, Twitter automatically crawls your site and fetches any Twitter Card metadata. To enable the automatic generation of Twitter Card metadata for your site, you can add the following to your _quarto.yml configuration file:

website:
  twitter-card: true

In this case, Quarto will automatically generate a title, description, and preview image for the content. For more information about how Quarto finds preview images, see Preview Images.

You may also provide additional metadata to be used when generating the Twitter Card, including:

Key Description
title The title of the page. Quarto will automatically use the title metadata from the page metadata. If you’d like you can override this just for the Twitter Card by including a title in the twitter-card metadata.
description A short description of the content. Quarto will automatically use the description metadata from the page metadata. If you’d like you can override this just for the Twitter Card by including a description in the twitter-card metadata.
image

The path to a preview image for this content. By default, Quarto will use the image value from the document metadata, or if that isn’t specified, the image value from the website: metadata. If you provide an image, you may also optionally provide an image-width and image-height to improve the appearance of your Twitter Card.

If image is not provided, Quarto will automatically attempt to locate a preview image. For more information, see Preview Images.

card-style Either 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. Note that strings with special characters such as @ must be quoted in yaml.
site @username of website. Note that strings with special characters such as @ must be quoted in yaml.

Here is a more comprehensive example of specifying Twitter Card metadata in a quarto.yml file:

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

Quarto will automatically merge global metadata found in the website: twitter-card key with any metadata provided in the document itself in the twitter-card key. This is useful when you need to specify a mix of global options (for example, site) with per document options such as title or image.

Open Graph

The Open Graph protocol is a specification that enables richer sharing of links to articles on the web. It will improve the previews of your content when a link to it is pasted into applications like Slack, Discord, Facebook, Linkedin, and more. To enable the automatic generation of Open Graph metadata for your content, include the following in your _quarto.yml configuration file:

website:
  open-graph: true

In this case, Quarto will automatically generate a title, description, and preview image for the content. For more information about how Quarto finds preview images, see Preview Images.

You may also provide additional metadata to be used when generating the Open Graph metadata, including:

Key Description
title The title of the page. Quarto will automatically use the title metadata from the page metadata. If you’d like you can override this just for the Open Graph metadata by including a title in the open-graph metadata.
description A short description of the content. Quarto will automatically use the description metadata from the page metadata. If you’d like you can override this just for the Open Graph metadata by including a description in the open-graph metadata.
image

The path to a preview image for this content. By default, Quarto will use the image value from the document metadata, or if that isn’t specified, the image value from the website: metadata. If you provide an image, you may also optionally provide an image-width and image-height to improve the appearance of your Twitter Card.

If image is not provided, Quarto will automatically attempt to locate a preview image. For more information, see Preview Images.

locale The locale that the Open Graph metadata is marked up in.
site-name The name which should be displayed for the overall site. If not explicitly provided in the open-graph metadata, Quarto will use the website:title value.

Here is a more comprehensive example of specifying Open Graph metadata in a quarto.yml file:

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

Quarto will automatically merge global metadata found in the website: open-graph key with any metadata provided in the document itself in the open-graph key. This is useful when you need to specify a mix of global options (for example, site) with per document options such as title or image.

Preview Images

You can specify a preview image for your article in several different ways:

  1. Full URL: You can explicitly provide a full url to the preview image using the image field in the appropriate metadata. For example:

    page.qmd
    title: "My Document"
    image: "https://quarto.org/docs/websites/images/tools.png"
  2. Relative Path: You may provide a document relative path to an image (such as images/preview-code.png) or a project relative path to an image (such as /images/preview-code.png). If you provide a relative path such as this, you must also provide a site-url in your site’s metadata. For example in your _quarto.yml configuration file:

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

    and in your document front matter:

    page.qmd
    title: "My Document"
    image: "/docs/websites/images/tools.png"
  3. Image Class: Any image that is being rendered in the page may also be used as a preview image by giving it the class name preview-image. Quarto will select the first image it finds with this class. For example, the following image will be used as the preview image when included on a page:

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

    If you label an image with this class, you must also provide a site-url in your site’s metadata.

  4. Image Filename: If none of the above ways of specifying a preview image have been used, Quarto will attempt to find a preview image by looking for an image included in the rendered document with one of the following names: preview.png, feature.png, cover.png, or thumbnail.png.

If you’d like to provide a default that is used when pages specify a preview image in none of the above ways, specify it at the site level:

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

If you would like to prevent preview image discovery on a page, set image to false:

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

Google Analytics

You can add Google Analytics to your website by adding adding a google-analytics key to your _quarto.yml file. In its simplest form, you can just pass your Google Analytics tracking Id (e.g. UA-xxxxxxx) or Google Tag measurement Id (e.g. G-xxxxxxx) like:

website:
  google-analytics: "UA-XXXXXXXX"

Quarto will use the key itself to determine whether to embed Google Analytics (analytics.js) or Google Tags (gtag) as appropriate.

In addition to this basic configuration, you can exercise more fine grained control of your site analytics using the following keys.

Key Description
tracking-id The Google tracking Id or measurement Id of this website.
storage

cookies - Use cookies to store unique user and session identification (default).

none - Do not use cookies to store unique user and session identification.

For more about choosing storage options see Storage.

anonymize-ip Anonymize the user ip address. For more about this feature, see IP Anonymization (or IP masking) in Google Analytics.
version The version number of Google Analytics to use. Currently supports either 3 (for analytics.js) or 4 (for gtag). This is automatically detected based upon the tracking-id, but you may specify it.

Storage

Google Analytics uses cookies to distinguish unique users and sessions. If you choose to use cookies to store this user data, you should consider whether you need to enable Cookie Consent in order to permit the viewer to control any tracking that you enable.

If you choose none for storage, this will have the following effects:

  • For Google Analytics v3 (analytics.js)
    No tracking cookies will be used. Individual page hits will be properly tracked, enabling you to see which pages are viewed and how often they are viewed. Unique user and session tracking will not report data correctly since the tracking cookies they rely upon are not set.

  • For Google Tags (gtag)
    User consent for ad and analytics tracking cookies will be withheld. In this mode, Google Analytics will still collect user data without the user identification, but that data is currently not displayed in the Google Analytics reports.

Site Resources

Besides input and configuration files, your site likely also includes a variety of resources (e.g. images) that you will want to publish along with your site. Quarto will automatically detect any files that you reference within your site and copy them to the output directory (e.g. _site).

If this auto-detection fails for any reason, or if you want to publish a file not explicitly linked to from within your site, you can add a resources entry to your configuration. For example, here we specify that we want to include all Excel spreadsheets within the project directory as part of the website:

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

Note that the *.xslx value is quoted: this is because YAML requires that strings that begin with non-alphanumeric characters be quoted.

You can also add a resources metadata value to individual files. For example:

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

Images are the most commonly used type of resource file. If you have global images (e.g. a logo) that you want to reference from various pages within your site, you can use a site-absolute path to refer to the images, and it will be automatically converted to a relative path during publishing. For example:

![](/images/logo.png)

Dark Mode

Quarto websites can support both a light and dark mode. For example, you may use the flatly and darkly themes (which are designed to be used in tandem as dark and light appearances) as:

theme:
  light: flatly
  dark: darkly

For more about selecting the dark and light themes for your website, see Dark Mode.

Light Dark
A Quarto sidebar showing a light theme. The 'Dark mode' toggle is off. A Quarto sidebar showing a dark theme. The 'Dark mode' toggle is on.

When enabled, a toggle that allows your reader to control the appearance of the website will appear. The toggle will automatically be added to the website navigation as follows:

  1. If a navbar has been specified, the toggle will appear in the top right corner of the nav bar.
  2. If there is no navbar present, but a sidebar has been specified, the toggle will appear in the same location that the sidebar tools appears (adjacent to the title or logo in the sidebar).
  3. If there is no navbar or sidebar present, the toggle will appear in the top right corner of the page.