Replace prerelease-link-subdomain with version-aware shortcode

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,62 @@
+-- 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, raw_args, context)
+  local ref_version = quarto.shortcode.read_arg(args, 1)
+  if ref_version == nil then
+    return quarto.shortcode.error_output(
+      "prerelease-docs-url",
+      "requires a version argument, e.g. {{< prerelease-docs-url 1.9 >}}",
+      context
+    )
+  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
+
+  -- Guard against missing or invalid version metadata
+  local version_str = meta["version"] and pandoc.utils.stringify(meta["version"]) or nil
+  if not version_str or version_str == "" then
+    return quarto.shortcode.error_output(
+      "prerelease-docs-url",
+      "missing 'version' in document metadata",
+      context
+    )
+  end
+
+  -- Compare referenced version to this branch's version using
+  -- pandoc.types.Version for correct element-wise comparison (1.12 > 1.9)
+  local ok_branch, branch_version = pcall(pandoc.types.Version, version_str)
+  local ok_ref, ref = pcall(pandoc.types.Version, ref_version)
+
+  if not ok_branch then
+    return quarto.shortcode.error_output(
+      "prerelease-docs-url",
+      "invalid metadata version '" .. version_str .. "'",
+      context
+    )
+  end
+  if not ok_ref then
+    return quarto.shortcode.error_output(
+      "prerelease-docs-url",
+      "invalid version argument '" .. ref_version .. "'",
+      context
+    )
+  end
+
+  if ref <= 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.

_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
 

docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd

@@ -83,9 +83,9 @@ Quarto's Markdown-based workflow handles many accessibility requirements automat
 But you do need to make sure your document has:
 
 * A **title** in the YAML front matter.
-* **Alt text for every image**, specified with `fig-alt`. See [Figures](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/authoring/figures.html#alt-text) for details.
+* **Alt text for every image**, specified with `fig-alt`. See [Figures](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/authoring/figures.html#alt-text) for details.
 
-See the [LaTeX](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/pdf-basics.html#accessibility-requirements) and [Typst](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/typst.html#accessibility-requirements) documentation for more details.
+See the [LaTeX](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/output-formats/pdf-basics.html#accessibility-requirements) and [Typst](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/output-formats/typst.html#accessibility-requirements) documentation for more details.
 
 ## If your document fails validation
 
@@ -101,7 +101,7 @@ We ran our test suite -- 188 LaTeX examples and 317 Typst examples -- to find wh
 
 Margin content is the biggest structural blocker. If you use `.column-margin` divs, `cap-location: margin`, `reference-location: margin`, or `citation-location: margin`, the resulting PDF will not pass UA-2. The underlying `sidenotes` and `marginnote` LaTeX packages [do not cooperate with PDF tagging](https://github.com/quarto-dev/quarto-cli/issues/14103). 
 
-(Margin content does work with Typst and passes UA-1 -- see [Typst Article Layout](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/output-formats/typst.html#article-layout).)
+(Margin content does work with Typst and passes UA-1 -- see [Typst Article Layout](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/output-formats/typst.html#article-layout).)
 
 There are smaller upstream issues in Pandoc, LaTeX, and LaTeX packages, [documented here](https://github.com/quarto-dev/quarto-cli/pull/14097#issuecomment-3947653207).
 
@@ -111,7 +111,7 @@ In our tests, Typst catches every UA-1 violation, and fails to generate the PDF.
 
 Typst also seems to do a very good job of generating UA-1 compliant output by default -- almost all errors were due to missing titles or missing alt text.
 
-However, we did discover that [Typst books](https://{{< meta prerelease-link-subdomain >}}quarto.org/docs/books/book-output.html#typst-output) are not yet compliant. There is a [structural problem with the Typst orange-book package](https://github.com/flavio20002/typst-orange-template/issues/38) and we'll work with the maintainers to correct it.
+However, we did discover that [Typst books](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/books/book-output.html#typst-output) are not yet compliant. There is a [structural problem with the Typst orange-book package](https://github.com/flavio20002/typst-orange-template/issues/38) and we'll work with the maintainers to correct it.
 
 ## Conclusion