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:

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"
```
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"
```
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.
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.

Cookie Consent

Quarto includes the ability to request cookie consent before enabling scripts that set cookies, using Cookie Consent.

The user’s cookie preferences will automatically control Google Analytics (if enabled) and can be used to control custom scripts you add as well (see Custom Scripts and Cookie Consent). You can enable the default request for cookie consent using the following:

website:
  cookie-consent: true

You can further customize the appearance and behavior of the consent using the following:

Key	Description
`type`	The type of consent that should be requested, using one of these two values: implied - (default) This will notify the user that the site uses cookies and permit them to change preferences, but not block cookies unless the user changes their preferences. express - This will block cookies until the user expressly agrees to allow them (or continue blocking them if the user doesn’t agree).
`style`	The style of the consent banner that is displayed: simple - (default) A simple dialog in the lower right corner of the website. headline - A full width banner across the top of the website. interstitial - An semi-transparent overlay of the entire website. standalone - An opaque overlay of the entire website.
`palette`	Whether to use a dark or light appearance for the consent banner: light - A light colored banner. dark - A dark colored banner.
`language`	The language to be used when displaying the cookie consent prompt specified using an IETF language tag. If not specified, the document language will be used.
`policy-url`	The url to the website’s cookie or privacy policy.
`prefs-text`	The text to display for the cookie preferences link in the website footer.

A custom example might look more like:

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

Cookie Preferences

In addition to requesting consent when a new user visits your website, Cookie Consent will also add a cookie preferences link to the footer of the website. You can control the text of this link using prefs-text. If you would rather position this link yourself, just add a link with the id #open_preferences_center to the website and Cookie Consent will not add the preferences link to the footer. For example:

Change [cookie preferences]{#open_preferences_center}

Custom Scripts and Cookie Consent

Cookie Consent works by preventing the execution of scripts unless the user has expressed their consent. To control your custom scripts using Cookie Consent:

Insert script tags as type='text/plain' (when the user consents, the type will be switched to text/javascript and the script will be executed).

Add a cookie-consent attribute to your script tag, setting it one of the following 4 levels:

Level	Description
`strictly-necessary`	Strictly scripts are loaded automatically and cannot be disabled by the user.
`functionality`	Scripts that are required for basic functionality of the website, for example, remembering a user language preference.
`tracking`	Scripts that are used to track users, for example Google Analytics.
`targeting`	Scripts that are used for the purpose of advertising to ad targeting, for example Google AdSense remarketing.

An example script that is used for user tracking would look like:

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

// My tracking JS code here

</script>

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

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:

If a navbar has been specified, the toggle will appear in the top right corner of the nav bar.
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).
If there is no navbar or sidebar present, the toggle will appear in the top right corner of the page.