Creating a Website

Overview

Quarto Websites are a convenient way to publish groups of documents. Documents published as part of a website share navigational elements, rendering options, and visual style.

Website navigation can be provided through a global navbar, a sidebar with links, or a combination of both for sites that have multiple levels of content. You can also enable full text search for websites.

This site is an example of a Quarto Website (you can see the source code for it here: https://github.com/quarto-dev/quarto-web).

Getting Started

To create a new website project, use the Quarto create-project command:

quarto create-project mysite --type site

This will create the scaffolding for a simple website in the mysite sub-directory. Here is what the _quarto.yml config file will look like for the site:

project:
  type: site

site:
  title: "mysite"
  navbar:
    background: primary
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

To render the website into the _site directory:

cd mysite
quarto render

See the Project Basics article to learn more about working with projects.

RStudio

If you are using RStudio you can also create a Quarto website via the New Project command:

Render documents within the site using the Render command, render the entire site using the Render Site command on the Build tab.

Workflow

Quarto includes a live-reloading development server that you will likely find convenient to use while working on websites. Start the server with:

quarto preview

The browser will automatically refresh whenever you save a markdown file (.md) or Jupyter Notebook (.ipynb). The browser will also refresh whenever you render a .qmd file.

Changes to configuration files (e.g. _quarto.yml) as well as site resources (e.g. theme or CSS files) will also cause an automatic refresh.

If you are using RStudio a site development server will be run automatically when you render a document or the site. You can also start the development server directly using the Serve Site command on the Build tab.

Note that development server updates do not cause an update to the final site output. Consequently, you should always quarto render your site before deploying it, even if you have already previewed the changes with the development server.

Linking

When creating links between pages in your site, you can provide the source file as the link target (rather than the .html file). You can also add hash identifiers (#) to the source file if you want to link to a particular section in the document. For example:

[about](about.qmd)
[about](about.qmd#section)

One benefit of using this style of link as opposed to targeting .html files directly is that if you at some point convert your site to a book the file-based links will automatically resolve to section links for formats that produce a single file (e.g. PDF or MS Word).

Learning More

Once you’ve got a basic website up and running check out these articles for various ways to enhance your site:

Website Navigation describes various ways to add navigation to a website, including top-level navigation bars, sidebars, or hybrid designs that uses both. This article also covers adding full-text search as well as a site-wide footer.

Website Tools covers adding social metadata (e.g. for Twitter Cards) and Google Analytics to your site, as well as enabling users to toggle between dark and light color schemes.

Code Execution provides tips for optimizing the rendering of sites with large numbers of documents or expensive computations.

Publishing Websites enumerates the various options for publishing websites including GitHub Pages, Netlify, Google Firebase, and RStudio Connect.