Website Tools

Social Metadata

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

  • Twitter Cards
  • Open Graph

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:

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

site:
  twitter-card:
    creator: "@dragsonstyle"
    site: "@rstudio"

Quarto will automatically merge global metadata found in the site: 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:

site:
  opengraph: 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 site: metadata. If you provide an image, you may also optionally provide an image-width and image-height.

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 site:title value.

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

site:
  open-graph:
    locale: es_ES
    site_name: Quarto

Quarto will automatically merge global metadata found in the site: 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. You can explicitly provide a full url to the preview image using the image field in the appropriate metadata. For example:

    title: "My Document"
    twitter-card:
      image: "https://quarto.org/images/preview-code.png"
  2. 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:

    site:
      site-url: "https://www.quarto.org"

    and in your document front matter:

    title: "My Document"
    twitter-card:
      image: "/images/preview-code.png"
  3. 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/preview-code.png){.preview-image}

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

  4. 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 thumbail.png.

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:

site:
  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: site
  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.