The quarto-web repository (https://github.com/quarto-dev/quarto-web) is the documentation website for Quarto, serving two primary functions:
Documentation Website: Hosts the complete documentation for Quarto, the open-source scientific and technical publishing system. Content includes guides, tutorials, API references, and examples covering authoring, computations, output formats, publishing, and extensions.
Release Distribution System: Manages automated download infrastructure for Quarto CLI releases, providing version-agnostic URLs (/download/latest/* and /download/prerelease/*) that always point to current stable and prerelease versions.
The repository deploys to two parallel sites from a single codebase using Quarto's profile system:
The project is configured as a Quarto website in _quarto.yml1-240 with content organized under docs/. Both sites share the same source files but apply different configurations via profile-specific YAML files (_quarto-rc.yml1-4 _quarto-prerelease.yml1-3 _quarto-prerelease-docs.yml1-25).
Key Systems Documentation:
Sources: _quarto.yml1-240 _quarto-rc.yml1-4 _quarto-prerelease.yml1-3 _quarto-prerelease-docs.yml1-25 README.md110-154
Sources: _quarto.yml1-690 _redirects1-26 index.qmd1-342 docs/download/_prerelease.json1-88 docs/download/_download.json1-88
The quarto-web repository contains ten major interconnected systems:
| System | Purpose | Key Files |
|---|---|---|
| Release and Download | Tracks Quarto CLI releases (stable v1.8.27, prerelease v1.9.30) and provides version-agnostic download URLs | docs/download/_prerelease.json, docs/download/_download.json, _redirects |
| CI/CD Infrastructure | Automates rendering, deployment, and maintenance across production and prerelease environments | .github/workflows/publish.yml, .github/workflows/preview.yml, .github/workflows/update-downloads.yml |
| Website Configuration | Defines site structure, navigation, metadata, and publishing targets | _quarto.yml, docs/guide/guide.yml |
| Homepage and Entry | Landing page with hero banner, multi-language demos, and feature showcase | index.qmd, index.css, theme.scss |
| Extension Ecosystem | Catalog of 343+ community extensions (shortcodes, filters, formats, RevealJS) | _extensions/, YAML listing files |
| Document Authoring | Documentation for markdown syntax, computation engines, execution options, branding | docs/authoring/, docs/computations/ |
| Presentation System | Reveal.js integration documentation and interactive demo | docs/presentations/, demo/index.qmd |
| Dashboard System | Dashboard creation with Python/R/Julia/Observable | docs/dashboards/ |
| Gallery and Showcase | Community examples and use cases | docs/gallery/ |
| Publishing Workflows | Guides for deploying to various hosting platforms | docs/publishing/ |
Sources: _quarto.yml1-240 index.qmd1-14 docs/guide/guide.yml1-199 docs/download/_download.json1-88 docs/download/_prerelease.json1-88 _redirects1-26 .github/workflows/publish.yml1-91 .github/workflows/update-downloads.yml1-93 .github/workflows/preview.yml1-191
The repository uses execute.freeze: true (_quarto.yml or project settings) to cache computational results in _freeze/, preventing re-execution during CI builds. This allows the CI pipeline to run without R, Python, or Julia dependencies.
Sources: _quarto.yml1-240 README.md20-28 docs/publishing/netlify.qmd59-88 .github/workflows/publish.yml47-51
The repository maintains two parallel sites from a single codebase using Quarto's profile system:
Profile System Architecture:
The repository uses a two-layer profile system defined in _quarto.yml1-240:
Phase profiles (rc / prerelease): Control release-phase branding on quarto.org. Declared as a profile group in _quarto.yml, where first entry is default. Switching between "Release Candidate" and "Pre-release" branding is done by reordering this group.
Site profile (prerelease-docs): Configures infrastructure specific to prerelease.quarto.org, including site-url, announcement banner, search index name, and theme overrides.
The QUARTO_PROFILE environment variable in .github/workflows/publish.yml50-106 controls which profiles activate during CI builds.
Sources: _quarto.yml1-240 _quarto-rc.yml1-4 _quarto-prerelease.yml1-3 _quarto-prerelease-docs.yml1-25 .github/workflows/publish.yml1-91 .github/workflows/update-downloads.yml1-93 docs/download/_download.json1-88 docs/download/_prerelease.json1-88 _redirects1-26 README.md110-154
The _quarto.yml file defines the complete website structure:
The website.sidebar array defines four context-specific sidebars that activate based on the current page. Each sidebar references content from docs/guide/guide.yml or directly lists navigation items. The Algolia search configuration differs between sites: production uses prod_QUARTO index, prerelease uses prerelease_QUARTO.
Sources: _quarto.yml1-240 _quarto-prerelease-docs.yml1-25 docs/guide/guide.yml1-199
The homepage (index.qmd1-342) uses a custom layout with specific structural components:
The homepage uses page-layout: custom to disable default layout containers, allowing full-width hero section. The .hero-animation div contains two <video> elements with prefers-color-scheme media queries to switch between light/dark animations.
Sources: index.qmd1-14 index.css1-298
The repository includes comprehensive documentation for multiple publishing targets:
| Publishing Target | Documentation File | Key Features |
|---|---|---|
| Quarto Pub | docs/publishing/quarto-pub.qmd1-256 | Free hosting, QUARTO_PUB_AUTH_TOKEN, GitHub Actions |
| GitHub Pages | docs/publishing/github-pages.qmd1-341 | gh-pages branch, _redirects, freeze computations |
| Netlify | docs/publishing/netlify.qmd1-250 | NETLIFY_AUTH_TOKEN, build plugin, custom domains |
| Posit Connect | docs/publishing/rstudio-connect.qmd1-341 | CONNECT_SERVER, CONNECT_API_KEY, Git-backed content |
| Other Services | docs/publishing/other.qmd1-48 | Firebase, Site44, Amazon S3 |
| CI Publishing | docs/publishing/ci.qmd1-195 | Shell commands, freezing, credentials |
Each guide follows a consistent structure:
Sources: docs/publishing/quarto-pub.qmd1-256 docs/publishing/github-pages.qmd1-341 docs/publishing/netlify.qmd1-250 docs/publishing/rstudio-connect.qmd1-341 docs/publishing/other.qmd1-48 docs/publishing/ci.qmd1-195
The release management system is the most critical infrastructure component, automatically tracking two concurrent version streams:
Workflow Details:
The update-downloads.yml workflow runs every 15 minutes, queries the GitHub API for latest releases, regenerates _download.json and _prerelease.json, then commits changes if detected. This triggers publish.yml to deploy updated metadata to both sites.
Each JSON file contains:
version, name, created, updated, published timestampsassets[] array with name, download_url, checksum (SHA256), size for each platform packagedescription with full changelog textThe _redirects file maps version-agnostic URLs to GitHub release URLs, updated automatically when versions change.
Sources: .github/workflows/update-downloads.yml1-93 docs/download/_prerelease.json1-88 docs/download/_download.json1-88 _redirects1-26 _quarto.yml6-9
The repository relies on several core technologies:
prod_QUARTO) and prerelease (prerelease_QUARTO)quarto-dev/quarto-actionsSources: _quarto.yml30-38 docs/publishing/github-pages.qmd159-168
Refresh this wiki