quarto-web

This is the repo for the documentation hosted at:

• Current release: quarto.org
• Pre-release: prerelease.quarto.org

Reporting Issues

Please report issues on quarto.org by opening a "Documentation Issue" in the quarto-dev/quarto-cli repository: New Issue

Rendering quarto-web locally

This section discusses how to contribute to the documentation by rendering a document locally.

Quarto-web uses a frozen state of computation

This Quarto project uses freeze: true, meaning it will never run computation engines during a project render. No Knitr or Jupyter configuration is needed to build the whole website. The _freeze folder is tracked on the git repo for this purpose. (See about freeze for a reminder of how this works).

What is the impact if you modify (or add) a document:

• If you modify a document that doesn't use any computation (i.e default engine: markdown is used), committing only the changes in the document is enough.
• If you modify a document that uses engine: knitr or engine: jupyter, you need to render the document locally and commit the changes in the _freeze folder as well. See incremental render.

Rendering the whole website

When you render quarto-web, you should use the current Pre-release of Quarto.

To render the whole website locally, you can use the following command:

# Update freeze state if needed
quarto render /docs/path/to/modified-or-added-document.qmd
# Render the whole website using freeze state for all the other docs
quarto render

Installing and managing computation environment

To manage computational dependencies this project uses

• renv for the R environment (https://rstudio.github.io/renv/) - it will be installed automatically first time the project is run with R.
• uv for the Python environment (https://docs.astral.sh/uv/) - Please install uv if you don't have it yet.

R environment for Knitr engine

This project uses R 4.3.2 and renv to manage its R dependencies. To install the R environment, you can use the following command at the project root:

Rscript -e "renv::restore()"

The project library will be located under the renv folder.

You don't need to worry about the R environment when you are working on this project. renv sets up .Rprofile to activate the project library when R is ran from the project's root. Just run your R code as usual, and renv will be activated automatically, meaning R will correctly use the project's library.

If you are adding a new document that may use a new package, follow these steps:

• Dependencies are explicitly declared in DESCRIPTION file. So add the new package to the list.
• Run renv::install('package_name') to add the new package to project library, and render your document to test everything is working fine.
• Run renv::snapshot() to update the renv.lock file with the new package and its dependencies.
• Commit the modified DESCRIPTION and renv.lock files with your document change (don't forget any change in the _freeze folder if needed).

Note: Python dependencies are not tracked through renv but are tracked with uv. See below

Python environment for Jupyter engine and Knitr through reticulate

This project uses uv (https://docs.astral.sh/uv/) to handle Python dependencies. uv takes care of managing dependencies and the virtual environment for you.

To install the Python environment, run the following command at the project root:

uv sync

If you don't have a matching Python version installed, uv will download one automatically.

The virtual environment will be located in the project directory under .venv.

To run a command using the project's Python environment, use uv run:

uv run quarto render docs/path/to/document.qmd

You can also activate the virtual environment directly:

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Inside VS Code, the Python extension should find the .venv Python version automatically (e.g. Python > Select Interpreter), which Quarto Preview uses. The integrated terminal will also use this Python version without manual activation.

If you are adding a new document that may use a new package, follow these steps:

• Run uv add <package_name> to add the new package to the project. It will update the pyproject.toml and uv.lock files with the new package and its dependencies.
• Commit the modified pyproject.toml and uv.lock files with your document changes (don't forget any changes in the _freeze folder if needed).

Documents running Python with the Knitr engine will go through reticulate. reticulate will use the Python version from .venv --- no specific configuration is needed as reticulate's python discovery mechanism will find it.

Reference pages are automatically generated

The tablular data on options listed in the Reference section are generated automatically by running:

quarto run _tools/reference.ts

This builds the .json files in docs/references based on the Quarto CLI schema. The script assumes you have quarto-cli/ at the same level in your directory structure as quarto-web/.

Profile System

This project uses Quarto profiles to build two sites from the same source: quarto.org and prerelease.quarto.org.

Two-layer architecture

Phase profiles (rc / prerelease) control release-phase branding. They are declared as a profile group in _quarto.yml:

profile:
  group:
    - [rc, prerelease]   # first entry is the default

The group order determines which phase is active on quarto.org (the main site). Flipping the order (e.g. [rc, prerelease] to [prerelease, rc]) switches the main site between "Release Candidate" and "Pre-release" branding.

File	Purpose
_quarto-prerelease.yml	Phase variables for the pre-release/development phase
_quarto-rc.yml	Phase variables for the release candidate phase

Site profile (prerelease-docs) configures everything specific to prerelease.quarto.org: site URL, announcement banner, search index, theme, and the prerelease-subdomain variable.

File	Purpose
_quarto-prerelease-docs.yml	Site-specific configuration for prerelease.quarto.org

CI profile (pr-preview) is used by the deploy preview workflow to render draft: true pages as visible. quarto render hides drafts by default, but PR reviewers need to see them.

File	Purpose
_quarto-pr-preview.yml	Sets draft-mode: visible for deploy previews

Subdomain variable and shortcode

prerelease-subdomain — site identity variable ("am I the prerelease site?"). Default '' in _quarto.yml, set to prerelease. in _quarto-prerelease-docs.yml. Use for self-referential links (e.g. RevealJS demo links back to its own site).

prerelease-docs-url — version-aware shortcode for content linking. Use in blog posts that reference docs only available on prerelease:

[PDF Accessibility](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/output-formats/pdf-accessibility.html)

The shortcode compares its version argument to the version key in _quarto.yml (which tracks the current stable release on main). If they match, docs are on quarto.org (""); if not, they're still on prerelease.quarto.org ("prerelease."). On the prerelease site (prerelease-docs profile), it always returns "prerelease.".

Release lifecycle

1. Development phase: group is [prerelease, rc] — main site shows "Pre-release"
2. RC phase: flip group to [rc, prerelease] — main site shows "Release Candidate"
3. Release: flip back to [prerelease, rc] for the next development cycle

These flips only affect quarto.org. The prerelease site CI activates prerelease-docs, and the group order determines the phase branding on the prerelease site too.

Local preview

# Main site with RC branding
quarto preview --profile rc

# Main site with pre-release branding (default when prerelease is first in group)
quarto preview

# Prerelease site
quarto preview --profile prerelease,prerelease-docs

GitHub Action Workflows

Our GitHub Action workflows are documented in .github/workflows/README.md

Style Guide

You can find some style guidance in _style-guide.md.