Replace prerelease-link-subdomain with version-aware shortcode

The `prerelease-link-subdomain` variable is phase-aware but not
version-aware — on the next RC cycle, old blog posts would incorrectly
point to prerelease.quarto.org even though those docs already moved
to quarto.org.

Add a `prerelease-docs-url` shortcode extension that compares a
version argument against the `version` key in `_quarto.yml` to decide
whether docs live on quarto.org or prerelease.quarto.org. On the
prerelease site (prerelease-docs profile), it always returns
"prerelease." regardless of version.

Follow-up to quarto-dev#1932, relates to quarto-dev#1934.

Author: cderv

README.md

@@ -132,24 +132,25 @@ The group order determines which phase is active on **quarto.org** (the main sit
 |---|---|
 | `_quarto-prerelease-docs.yml` | Site-specific configuration for prerelease.quarto.org |
 
-### Subdomain variables
+### Subdomain variable and shortcode
 
-Two variables control how links resolve across builds. Both use the same pattern — `https://{{< meta VAR >}}quarto.org/...` — but serve different purposes:
+**`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).
 
-| 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.` |
+**`prerelease-docs-url`** — version-aware shortcode for content linking. Use in blog posts that reference docs only available on 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).
+```markdown
+[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 explicitly activates `prerelease,prerelease-docs`, so it always shows "Pre-release" regardless of group order.
+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
 

_extensions/prerelease-docs-url/_extension.yml

@@ -0,0 +1,6 @@
+title: Prerelease Docs URL
+author: Quarto
+version: 0.0.1
+contributes:
+  shortcodes:
+    - prerelease-docs-url.lua

_extensions/prerelease-docs-url/prerelease-docs-url.lua

@@ -0,0 +1,32 @@
+-- Version-aware shortcode for linking to prerelease docs.
+--
+-- Usage: {{< prerelease-docs-url 1.9 >}}
+--
+-- Returns "prerelease." when the referenced version's docs live on
+-- prerelease.quarto.org, or "" when they're on quarto.org.
+
+local function handler(args, kwargs, meta)
+  local ref_version = quarto.shortcode.read_arg(args, 1)
+  if ref_version == nil then
+    quarto.log.error("prerelease-docs-url requires a version argument, e.g. {{< prerelease-docs-url \"1.9\" >}}")
+    return pandoc.Str("")
+  end
+  -- Strip surrounding quotes that may be preserved in text contexts
+  ref_version = ref_version:gsub('^"(.*)"$', '%1'):gsub("^'(.*)'$", '%1')
+
+  -- On the prerelease site, always link to prerelease
+  if quarto.project.profile:includes("prerelease-docs") then
+    return pandoc.Str("prerelease.")
+  end
+
+  -- Compare referenced version to this branch's version
+  local branch_version = pandoc.utils.stringify(meta["version"])
+
+  if ref_version == branch_version then
+    return pandoc.Str("")
+  else
+    return pandoc.Str("prerelease.")
+  end
+end
+
+return {["prerelease-docs-url"] = handler}

_quarto-prerelease-docs.yml

@@ -1,8 +1,7 @@
 # Pre-release version number
-version: v1.9
+version: '1.9'
 
 prerelease-subdomain: prerelease.
-prerelease-link-subdomain: prerelease.
 
 website:
   title: "Quarto (Pre-release)"
@@ -11,7 +10,7 @@ website:
   repo-branch: prerelease
   announcement:
     dismissable: false
-    content: "Pre-release ({{< meta version >}}) Documentation: [Download {{< meta version >}}](/docs/download/prerelease.qmd), [Current Release Docs](http://quarto.org) "
+    content: "Pre-release (v{{< meta version >}}) Documentation: [Download v{{< meta version >}}](/docs/download/prerelease.qmd), [Current Release Docs](http://quarto.org) "
   navbar:
     pinned: true
   search:

_quarto-rc.yml

@@ -1,4 +1,3 @@
 prerelease-title: Release Candidate
 prerelease-lower: release candidate
-prerelease-mode: Release Candidate
-prerelease-link-subdomain: prerelease.
+prerelease-mode: Release Candidate

_quarto.yml

@@ -706,8 +706,8 @@ filters:
   - at: post-quarto
     path: filters/include-dark.lua
 
+version: '1.8'
 prerelease-subdomain: ''
-prerelease-link-subdomain: ''
 
 freeze: true