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.
• pipenv for the Python environment (https://pipenv.pypa.io/en/latest/) - Please install pipenv manually 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 pipenv. See below

Python environment for Jupyter engine and Knitr through reticulate

This project uses pipenv (https://pipenv.pypa.io/zh-cn/stable/index.html) to handle the Python dependencies. pipenv takes care of managing dependencies and virtual environments for you.

To install the Python environment, you can use the following command at the project root:

pipenv sync

If you are using pyenv to manage your python installation, pipenv will ask you to install a newer version of python if the one currently used does not match the one from Pipfile.lock. Though, the exact match of version isn't required and this should not be a problem to not upgrade your python installation.

The virtual environment will be located in the project directory under .venv (following the configuration of pipenv set in the .env file).

When in the root of the project, you can run pipenv shell to activate the virtual environment associated with the project. Any quarto command should then use the correct python environment. You can also run pipenv run quarto ... to run the quarto command in the virtual environment without activating it.

Inside VSCODE, The Python extension should find the same Python version (e.g. Python > Select Interpreter) which Quarto Preview uses. As this extension integrates also in the terminal, it should use the same Python version in the terminal as well without needing to use pipenv shell or pipenv run.

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

• Run pipenv install <package_name> to add the new package to the project. It will update the Pipfile and Pipfile.lock files with the new package and its dependencies.
  • Pipfile could be manually edited but using the command is recommended.
• Commit the modified Pipfile and Pipfile.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 defined with pipenv when a PipFile is present. So, it 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

Subdomain variables

Two variables control how links resolve across builds. Both use the same pattern — https://{{< meta VAR >}}quarto.org/... — but serve different purposes:

Variable	Purpose	Default	Set by rc	Set by prerelease-docs
prerelease-subdomain	Site identity — "am I the prerelease site?"	''	—	prerelease.
prerelease-link-subdomain	Content linking — "where do prerelease docs live right now?"	''	prerelease.	prerelease.

Use prerelease-subdomain for self-referential links (e.g. RevealJS demo links back to its own site). Use prerelease-link-subdomain for content on main that references docs only available on prerelease during RC phase (e.g. blog posts announcing upcoming features).

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 explicitly activates prerelease,prerelease-docs, so it always shows "Pre-release" regardless of group order.

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.