diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index c450e4f77..d32b6a202 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -103,7 +103,7 @@ jobs: - name: Render uses: quarto-dev/quarto-actions/render@v2 env: - QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease-docs' || '' }} + QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease,prerelease-docs' || '' }} - name: Deploy Preview to Netlify as preview id: netlify-deploy diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 787d467de..e35cbc3b4 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -47,7 +47,7 @@ jobs: - name: Render uses: quarto-dev/quarto-actions/render@v2 env: - QUARTO_PROFILE: ${{ (inputs.prerelease || (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) && github.ref == 'refs/heads/prerelease')) && 'prerelease-docs' || '' }} + QUARTO_PROFILE: ${{ (inputs.prerelease || (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) && github.ref == 'refs/heads/prerelease')) && 'prerelease,prerelease-docs' || '' }} - name: Publish release website # Only do this step if diff --git a/README.md b/README.md index 4b133d143..1f39df086 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,65 @@ quarto run tools/reference.ts This builds the `.json` files in `docs/references` based on the [Quarto CLI schema](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/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](https://quarto.org/docs/projects/profiles.html) to build two sites from the same source: [quarto.org](https://quarto.org/) and [prerelease.quarto.org](https://prerelease.quarto.org/). + +### Two-layer architecture + +**Phase profiles** (`rc` / `prerelease`) control release-phase branding. They are declared as a [profile group](https://quarto.org/docs/projects/profiles.html#profile-groups) in `_quarto.yml`: + +```yaml +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 + +```bash +# 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`](.github/workflows/README.md) diff --git a/_quarto-prerelease-docs.yml b/_quarto-prerelease-docs.yml index bab775183..694420386 100644 --- a/_quarto-prerelease-docs.yml +++ b/_quarto-prerelease-docs.yml @@ -1,6 +1,9 @@ # Pre-release version number version: v1.9 +prerelease-subdomain: prerelease. +prerelease-link-subdomain: prerelease. + website: title: "Quarto (Pre-release)" image: "quarto-dark-bg-pre.jpeg" diff --git a/_quarto-prerelease.yml b/_quarto-prerelease.yml index c35504b53..9484b55b4 100644 --- a/_quarto-prerelease.yml +++ b/_quarto-prerelease.yml @@ -1,4 +1,3 @@ prerelease-title: Pre-release prerelease-lower: pre-release -prerelease-mode: "" -prerelease-subdomain: prerelease. \ No newline at end of file +prerelease-mode: "" \ No newline at end of file diff --git a/_quarto-rc.yml b/_quarto-rc.yml index 0f2c2e4d6..7d68f7fe2 100644 --- a/_quarto-rc.yml +++ b/_quarto-rc.yml @@ -1,4 +1,4 @@ prerelease-title: Release Candidate prerelease-lower: release candidate prerelease-mode: Release Candidate -prerelease-subdomain: '' \ No newline at end of file +prerelease-link-subdomain: prerelease. \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index 3b7c92327..5523ff3d7 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -712,6 +712,9 @@ filters: - at: post-quarto path: filters/include-dark.lua +prerelease-subdomain: '' +prerelease-link-subdomain: '' + freeze: true profile: