From 315f506e89215b54a875cf919f80c5190770c338 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:17:03 +0100
Subject: [PATCH 1/7] Consolidate prerelease extension with new
 prerelease-callout shortcode

Rename _extensions/prerelease-docs-url/ to _extensions/prerelease/ and
combine both shortcodes into a single Lua file with shared helpers:

- prerelease-docs-url: existing shortcode for prerelease subdomain links
- prerelease-callout: new shortcode that shows version-aware callouts
  for feature docs (hidden after release) and blog posts (switches from
  pre-release to released text)
---
 .../prerelease-docs-url.lua                   |  62 -------
 .../_extension.yml                            |   4 +-
 _extensions/prerelease/prerelease.lua         | 152 ++++++++++++++++++
 3 files changed, 154 insertions(+), 64 deletions(-)
 delete mode 100644 _extensions/prerelease-docs-url/prerelease-docs-url.lua
 rename _extensions/{prerelease-docs-url => prerelease}/_extension.yml (50%)
 create mode 100644 _extensions/prerelease/prerelease.lua

diff --git a/_extensions/prerelease-docs-url/prerelease-docs-url.lua b/_extensions/prerelease-docs-url/prerelease-docs-url.lua
deleted file mode 100644
index 6e4fd947f..000000000
--- a/_extensions/prerelease-docs-url/prerelease-docs-url.lua
+++ /dev/null
@@ -1,62 +0,0 @@
--- 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}
diff --git a/_extensions/prerelease-docs-url/_extension.yml b/_extensions/prerelease/_extension.yml
similarity index 50%
rename from _extensions/prerelease-docs-url/_extension.yml
rename to _extensions/prerelease/_extension.yml
index dabdf77cf..628a0a7f5 100644
--- a/_extensions/prerelease-docs-url/_extension.yml
+++ b/_extensions/prerelease/_extension.yml
@@ -1,6 +1,6 @@
-title: Prerelease Docs URL
+title: Prerelease
 author: Quarto
 version: 0.0.1
 contributes:
   shortcodes:
-    - prerelease-docs-url.lua
+    - prerelease.lua
diff --git a/_extensions/prerelease/prerelease.lua b/_extensions/prerelease/prerelease.lua
new file mode 100644
index 000000000..802284181
--- /dev/null
+++ b/_extensions/prerelease/prerelease.lua
@@ -0,0 +1,152 @@
+-- Version-aware shortcodes for prerelease content.
+--
+-- prerelease-docs-url:
+--   {{< 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.
+--
+-- prerelease-callout:
+--   {{< prerelease-callout 1.9 >}}
+--   Shows a "Pre-release Feature" callout when the referenced version is
+--   unreleased. Shows nothing once the version is released.
+--
+--   {{< prerelease-callout 1.9 type="blog" >}}
+--   Blog mode: shows "Pre-release Feature" callout when unreleased,
+--   switches to "Quarto X.Y Feature" callout once released.
+--
+-- Both shortcodes use the `version` key from _quarto.yml metadata and
+-- the `prerelease-docs` profile to determine whether a version is released.
+
+--- Strip surrounding quotes from a shortcode argument.
+local function strip_quotes(s)
+  return s:gsub('^"(.*)"$', '%1'):gsub("^'(.*)'$", '%1')
+end
+
+--- Parse the version argument and site version metadata.
+-- Returns ref_version, branch_version (as pandoc.types.Version), or
+-- nil plus an error Blocks/Inlines on failure.
+local function parse_versions(shortcode_name, args, meta, context)
+  local ref_str = quarto.shortcode.read_arg(args, 1)
+  if ref_str == nil then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "requires a version argument, e.g. {{< " .. shortcode_name .. " 1.9 >}}",
+      context
+    )
+  end
+  ref_str = strip_quotes(ref_str)
+
+  local version_str = meta["version"] and pandoc.utils.stringify(meta["version"]) or nil
+  if not version_str or version_str == "" then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "missing 'version' in document metadata",
+      context
+    )
+  end
+
+  local ok_branch, branch_version = pcall(pandoc.types.Version, version_str)
+  if not ok_branch then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "invalid metadata version '" .. version_str .. "'",
+      context
+    )
+  end
+
+  local ok_ref, ref_version = pcall(pandoc.types.Version, ref_str)
+  if not ok_ref then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "invalid version argument '" .. ref_str .. "'",
+      context
+    )
+  end
+
+  return ref_version, branch_version, nil
+end
+
+--- Check whether a referenced version is unreleased.
+-- On prerelease site (profile prerelease-docs): ref >= site version
+-- On main site: ref > site version
+local function is_unreleased(ref_version, branch_version)
+  if quarto.project.profile:includes("prerelease-docs") then
+    return ref_version >= branch_version
+  else
+    return ref_version > branch_version
+  end
+end
+
+--- Parse a markdown string into pandoc Blocks.
+local function md_to_blocks(md)
+  return pandoc.read(md, "markdown").blocks
+end
+
+-- Shortcode: prerelease-docs-url
+local function docs_url_handler(args, kwargs, meta, raw_args, context)
+  local ref_version, branch_version, err = parse_versions(
+    "prerelease-docs-url", args, meta, context
+  )
+  if err then return err end
+
+  -- On the prerelease site, always link to prerelease
+  if quarto.project.profile:includes("prerelease-docs") then
+    return pandoc.Str("prerelease.")
+  end
+
+  if ref_version <= branch_version then
+    return pandoc.Str("")
+  else
+    return pandoc.Str("prerelease.")
+  end
+end
+
+-- Shortcode: prerelease-callout
+local function callout_handler(args, kwargs, meta, raw_args, context)
+  local ref_version, branch_version, err = parse_versions(
+    "prerelease-callout", args, meta, context
+  )
+  if err then return err end
+
+  local ref_str = strip_quotes(quarto.shortcode.read_arg(args, 1))
+  local callout_type = kwargs["type"] or ""
+  local is_blog = callout_type == "blog"
+  local unreleased = is_unreleased(ref_version, branch_version)
+
+  if unreleased then
+    -- Pre-release callout (both feature docs and blog)
+    local content = md_to_blocks(
+      "This feature is new in the upcoming Quarto " .. ref_str .. " release. " ..
+      "To use the feature now, you'll need to " ..
+      "[download and install](/docs/download/prerelease.qmd) " ..
+      "the Quarto pre-release."
+    )
+    return quarto.Callout({
+      type = "note",
+      title = "Pre-release Feature",
+      content = content,
+    })
+  end
+
+  if is_blog then
+    -- Released blog callout
+    local content = md_to_blocks(
+      "This post is part of a series highlighting new features in the " ..
+      ref_str .. " release of Quarto. Get the latest release on the " ..
+      "[download page](/docs/download/index.qmd)."
+    )
+    return quarto.Callout({
+      type = "note",
+      title = "Quarto " .. ref_str .. " Feature",
+      content = content,
+    })
+  end
+
+  -- Feature docs, already released: show nothing
+  return pandoc.Blocks({})
+end
+
+return {
+  ["prerelease-docs-url"] = docs_url_handler,
+  ["prerelease-callout"] = callout_handler,
+}

From e9a06dff7c94dcf614028ff3e1f98539a39d1722 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:25:52 +0100
Subject: [PATCH 2/7] Replace _pre-release-feature includes with
 prerelease-callout shortcode

Migrate 5 include references across 3 files (all version 1.5, already
released) to use the new version-aware shortcode instead.
---
 docs/advanced/jupyter/kernel-execution.qmd | 6 +++---
 docs/computations/julia.qmd                | 2 +-
 docs/publishing/hugging-face.qmd           | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/advanced/jupyter/kernel-execution.qmd b/docs/advanced/jupyter/kernel-execution.qmd
index 9f261f318..c9ebb994b 100644
--- a/docs/advanced/jupyter/kernel-execution.qmd
+++ b/docs/advanced/jupyter/kernel-execution.qmd
@@ -25,7 +25,7 @@ In `python` and `julia` kernels, the setup and cleanup cells are defined by the
 
 ### Adding support to a Jupyter kernel
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 If a Jupyter kernel wants to execute in awareness of Quarto's context, it should signal its support by adding the following files to the kernelspec directory:
 
@@ -42,7 +42,7 @@ See the [source for more](https://github.com/quarto-dev/quarto_echo_kernel).
 
 ## Quarto document options
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 Jupyter kernels can have access to a number of Quarto options that can affect cell execution.
 
@@ -74,7 +74,7 @@ Quarto offers built-in support for `julia` and `python` kernels by default, see
 
 ### Adding support to a Jupyter kernel
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 Arbitrary Jupyter kernels can indicate support for daemons. To do so, provide a `quarto_setup_cell` file in the kernelspec directory so that setup cells can be executed, and ensure that the execution of the setup cell returns an output result with metadata indicating support for running as a daemon. The supported metadata options are:
 
diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd
index 1ce13b247..0376d3afd 100644
--- a/docs/computations/julia.qmd
+++ b/docs/computations/julia.qmd
@@ -108,7 +108,7 @@ display(plot(x -> sin(4x), y -> sin(5y), 0, 2))
 
 # Using the `julia` engine
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 ## Installation {#installation-julia-engine}
 
diff --git a/docs/publishing/hugging-face.qmd b/docs/publishing/hugging-face.qmd
index 8f91fbf58..8bdffd2e0 100644
--- a/docs/publishing/hugging-face.qmd
+++ b/docs/publishing/hugging-face.qmd
@@ -80,7 +80,7 @@ You can edit these files directly in the Hugging Face UI but we reccommend cloni
 
 ## Publish Command
 
-{{< include ../prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 The `quarto publish huggingface` command facilitates a workflow where you [make and preview edits](#edit-and-preview) locally before [publishing](#publish) to your Hugging Face space. Before using the command you'll need to complete some [Setup](#setup).
 

From ba70a5a53b2edf46ecd5d2dda7ac97c536416ee2 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:27:45 +0100
Subject: [PATCH 3/7] Replace blog post feature includes with
 prerelease-callout shortcode

Migrate 5 blog posts to use {{< prerelease-callout X.Y type="blog" >}}
instead of including shared _quarto-X.Y-feature.qmd files.
---
 docs/blog/posts/2023-03-13-code-annotation/index.qmd            | 2 +-
 docs/blog/posts/2023-03-15-multi-format/index.qmd               | 2 +-
 docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd     | 2 +-
 docs/blog/posts/2023-03-20-confluence/index.qmd                 | 2 +-
 .../posts/2026-03-05-pdf-accessibility-and-standards/index.qmd  | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/blog/posts/2023-03-13-code-annotation/index.qmd b/docs/blog/posts/2023-03-13-code-annotation/index.qmd
index 21fb694c9..8488de312 100644
--- a/docs/blog/posts/2023-03-13-code-annotation/index.qmd
+++ b/docs/blog/posts/2023-03-13-code-annotation/index.qmd
@@ -14,7 +14,7 @@ image-alt: "Screenshot a code chunk with annotations. Annotations appear in the
 code-annotations: below
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Code blocks and executable code cells in Quarto may now include line-based annotations. Line-based annotations provide a way to attach explanation to lines of code much like footnotes.
 
diff --git a/docs/blog/posts/2023-03-15-multi-format/index.qmd b/docs/blog/posts/2023-03-15-multi-format/index.qmd
index 89bc6781f..7d065fd9c 100644
--- a/docs/blog/posts/2023-03-15-multi-format/index.qmd
+++ b/docs/blog/posts/2023-03-15-multi-format/index.qmd
@@ -17,7 +17,7 @@ format:
   docx: default
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Starting in Quarto 1.3, HTML pages (either standalone or in a website) can automatically include links to other formats specified in the document front matter. For example, the following document front matter:
 
diff --git a/docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd b/docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd
index 22f07a3e9..368d19b66 100644
--- a/docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd
+++ b/docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd
@@ -13,7 +13,7 @@ image: embed.png
 image-alt: "A screenshot of a Quarto page that includes a plot, below the plot is the phrase Source: penguins.ipynb."
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Starting in Quarto 1.3, you can include the output of an external Jupyter notebook in a Quarto document with the `embed` shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and a cell identifier. For example, this notebook called `penguins.ipynb` has a cell labelled `fig-bill-scatter`:
 
diff --git a/docs/blog/posts/2023-03-20-confluence/index.qmd b/docs/blog/posts/2023-03-20-confluence/index.qmd
index e27a83645..417fbabd3 100644
--- a/docs/blog/posts/2023-03-20-confluence/index.qmd
+++ b/docs/blog/posts/2023-03-20-confluence/index.qmd
@@ -13,7 +13,7 @@ image: confluence-logo-gradient-blue-attribution_rgb@2x.png
 image-alt: "Atlassian Confluence Logo"
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 [Atlassian Confluence](https://www.atlassian.com/software/confluence) is a publishing platform for supporting team collaboration. Confluence has a variety of hosting options which include both free and paid subscription plans.
 
diff --git a/docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd b/docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd
index 3de0ba61b..627fec2cb 100644
--- a/docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd
+++ b/docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd
@@ -8,7 +8,7 @@ image: thumbnail.png
 image-alt: "Quarto icon, PDF file icon, accessibility icon, and validation shield"
 ---
 
-{{< include ../_quarto-1.9-feature.qmd >}}
+{{< prerelease-callout 1.9 type="blog" >}}
 
 2025 was a big year for PDF accessibility. LaTeX and Typst both released support for PDF tagging and accessibility standards, just in time for new regulations in the [EU](https://en.wikipedia.org/wiki/European_Accessibility_Act) (June 2025) and [US](https://accessible.org/ada-title-ii-web-accessibility/) (April 2026).  
 

From 1a389e24004236bbdbe7c1184166aeb9afc1cb7e Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:30:36 +0100
Subject: [PATCH 4/7] Remove old pre-release feature include files

These files are no longer needed now that the prerelease-callout
shortcode generates callout content dynamically based on version.
---
 docs/blog/posts/_quarto-1.3-feature.qmd      | 5 -----
 docs/blog/posts/_quarto-1.9-feature.qmd      | 5 -----
 docs/prerelease/1.3/_pre-release-feature.qmd | 5 -----
 docs/prerelease/1.4/_pre-release-feature.qmd | 5 -----
 docs/prerelease/1.5/_pre-release-feature.qmd | 0
 docs/prerelease/1.6/_pre-release-feature.qmd | 5 -----
 docs/prerelease/1.7/_pre-release-feature.qmd | 5 -----
 docs/prerelease/1.8/_pre-release-feature.qmd | 0
 docs/prerelease/1.9/_pre-release-feature.qmd | 5 -----
 9 files changed, 35 deletions(-)
 delete mode 100644 docs/blog/posts/_quarto-1.3-feature.qmd
 delete mode 100644 docs/blog/posts/_quarto-1.9-feature.qmd
 delete mode 100644 docs/prerelease/1.3/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.4/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.5/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.6/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.7/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.8/_pre-release-feature.qmd
 delete mode 100644 docs/prerelease/1.9/_pre-release-feature.qmd

diff --git a/docs/blog/posts/_quarto-1.3-feature.qmd b/docs/blog/posts/_quarto-1.3-feature.qmd
deleted file mode 100644
index 2fa830a61..000000000
--- a/docs/blog/posts/_quarto-1.3-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: callout-note
-## Quarto 1.3 Feature
-
-This post is part of a series highlighting new features in the 1.3 release of Quarto. Get the latest release the [download page](/docs/download/index.qmd)
-:::
diff --git a/docs/blog/posts/_quarto-1.9-feature.qmd b/docs/blog/posts/_quarto-1.9-feature.qmd
deleted file mode 100644
index 70e674e8f..000000000
--- a/docs/blog/posts/_quarto-1.9-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: callout-note
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.9 release. To use the feature now, you'll need to [download and install](/docs/download/prerelease.qmd) the Quarto pre-release.
-:::
diff --git a/docs/prerelease/1.3/_pre-release-feature.qmd b/docs/prerelease/1.3/_pre-release-feature.qmd
deleted file mode 100644
index 233ea1a59..000000000
--- a/docs/prerelease/1.3/_pre-release-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: {.callout-note}
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.3 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release.
-:::
diff --git a/docs/prerelease/1.4/_pre-release-feature.qmd b/docs/prerelease/1.4/_pre-release-feature.qmd
deleted file mode 100644
index 49c157a8c..000000000
--- a/docs/prerelease/1.4/_pre-release-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: {.callout-note}
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release.
-:::
diff --git a/docs/prerelease/1.5/_pre-release-feature.qmd b/docs/prerelease/1.5/_pre-release-feature.qmd
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/prerelease/1.6/_pre-release-feature.qmd b/docs/prerelease/1.6/_pre-release-feature.qmd
deleted file mode 100644
index 77d070491..000000000
--- a/docs/prerelease/1.6/_pre-release-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: {.callout-note}
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.6 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release.
-:::
diff --git a/docs/prerelease/1.7/_pre-release-feature.qmd b/docs/prerelease/1.7/_pre-release-feature.qmd
deleted file mode 100644
index ab049226f..000000000
--- a/docs/prerelease/1.7/_pre-release-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: {.callout-note}
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.7 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release.
-:::
diff --git a/docs/prerelease/1.8/_pre-release-feature.qmd b/docs/prerelease/1.8/_pre-release-feature.qmd
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/prerelease/1.9/_pre-release-feature.qmd b/docs/prerelease/1.9/_pre-release-feature.qmd
deleted file mode 100644
index eb8562bc3..000000000
--- a/docs/prerelease/1.9/_pre-release-feature.qmd
+++ /dev/null
@@ -1,5 +0,0 @@
-::: {.callout-note}
-## Pre-release Feature
-
-This feature is new in the upcoming Quarto 1.9 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release.
-:::

From caa44bf745fbb7ba392796d326a5b38bdce23dae Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:32:08 +0100
Subject: [PATCH 5/7] Add README for prerelease extension

Documents both shortcodes (prerelease-docs-url and prerelease-callout),
usage examples, and version comparison logic with scenario table.
---
 _extensions/prerelease/README.md | 52 ++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 _extensions/prerelease/README.md

diff --git a/_extensions/prerelease/README.md b/_extensions/prerelease/README.md
new file mode 100644
index 000000000..95cf8799f
--- /dev/null
+++ b/_extensions/prerelease/README.md
@@ -0,0 +1,52 @@
+# Prerelease Extension
+
+Version-aware shortcodes for prerelease content on quarto-web. Both shortcodes use the `version` key from `_quarto.yml` (or `_quarto-prerelease-docs.yml` on the prerelease profile) to determine whether a feature version has been released.
+
+## Shortcodes
+
+### `prerelease-docs-url`
+
+Returns `"prerelease."` when the referenced version's docs live on prerelease.quarto.org, or `""` when they're on quarto.org. Use in link URLs:
+
+```markdown
+[documentation](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/feature.html)
+```
+
+### `prerelease-callout`
+
+Shows a version-aware callout note. Two modes:
+
+**Feature docs** (default) — callout disappears after release:
+
+```markdown
+{{< prerelease-callout 1.9 >}}
+```
+
+- Unreleased: shows "Pre-release Feature" callout with link to prerelease download
+- Released: shows nothing
+
+**Blog posts** (`type="blog"`) — callout text changes after release:
+
+```markdown
+{{< prerelease-callout 1.9 type="blog" >}}
+```
+
+- Unreleased: shows "Pre-release Feature" callout with link to prerelease download
+- Released: shows "Quarto X.Y Feature" callout with link to stable download page
+
+## Version comparison logic
+
+On the **main site** (`version` = current stable release): a feature is unreleased when `ref_version > site_version`.
+
+On the **prerelease site** (profile `prerelease-docs`, `version` = current prerelease cycle): a feature is unreleased when `ref_version >= site_version`.
+
+The `>=` vs `>` difference handles the fact that the prerelease site's version equals the in-progress release, while main's version equals the last stable release.
+
+### Example scenarios (feature docs)
+
+| Phase | Site | `version` | ref | Unreleased? | Output |
+|---|---|---|---|---|---|
+| 1.9 in dev | main | 1.8 | 1.9 | 1.9 > 1.8 ✓ | Pre-release callout |
+| 1.9 in dev | prerelease | 1.9 | 1.9 | 1.9 >= 1.9 ✓ | Pre-release callout |
+| 1.9 released | main | 1.9 | 1.9 | 1.9 > 1.9 ✗ | Nothing |
+| 1.9 released | prerelease | 2.0 | 1.9 | 1.9 >= 2.0 ✗ | Nothing |

From 4563847fd17d38cc63112e16e27837578a113772 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 16:51:27 +0100
Subject: [PATCH 6/7] Replace remaining 1.9 _pre-release-feature includes with
 shortcode

Migrate 8 additional include references (only present on prerelease
branch) to use the version-aware prerelease-callout shortcode.
---
 docs/authoring/brand.qmd                | 2 +-
 docs/authoring/diagrams.qmd             | 2 +-
 docs/books/book-output.qmd              | 2 +-
 docs/extensions/engine.qmd              | 2 +-
 docs/output-formats/typst-custom.qmd    | 2 +-
 docs/output-formats/typst.qmd           | 2 +-
 docs/publishing/posit-connect-cloud.qmd | 2 +-
 docs/websites/website-search.qmd        | 2 +-
 8 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd
index 5af90da4f..578cbbc4e 100644
--- a/docs/authoring/brand.qmd
+++ b/docs/authoring/brand.qmd
@@ -780,7 +780,7 @@ In most cases, these assets should be committed to source control.
 
 ### `quarto use brand`
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 The `quarto use brand` command copies brand files from an external source into your project's `_brand/` directory. To use it, navigate to your project directory and run:
 
diff --git a/docs/authoring/diagrams.qmd b/docs/authoring/diagrams.qmd
index 7ef0dc2b1..4c50090e4 100644
--- a/docs/authoring/diagrams.qmd
+++ b/docs/authoring/diagrams.qmd
@@ -234,7 +234,7 @@ To include code for `{dot}`, add `//| echo: true` to the top of the cell. For ex
 
 ## Chrome Install {#chrome-install}
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 For printing to output formats like `pdf` or `docx`, diagram rendering makes use of the Chrome or Edge web browser to create a high-quality PNG.
 
diff --git a/docs/books/book-output.qmd b/docs/books/book-output.qmd
index b086fe6f0..cfc62b67d 100644
--- a/docs/books/book-output.qmd
+++ b/docs/books/book-output.qmd
@@ -159,7 +159,7 @@ At this point you should probably make a copy or git branch of the `_book` direc
 
 ## Typst Output
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 Quarto books can be rendered to PDF using [Typst](https://typst.app). When you specify `format: typst` for a book project, Quarto automatically uses the bundled [orange-book](https://typst.app/universe/package/orange-book) format extension, which provides textbook styling.
 
diff --git a/docs/extensions/engine.qmd b/docs/extensions/engine.qmd
index 12a59a194..44afd4fc8 100644
--- a/docs/extensions/engine.qmd
+++ b/docs/extensions/engine.qmd
@@ -2,7 +2,7 @@
 title: "Engine Extensions"
 ---
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 Engine extensions are Quarto extensions that provide an execution engine for running code blocks and capturing their output in Quarto documents.
 
diff --git a/docs/output-formats/typst-custom.qmd b/docs/output-formats/typst-custom.qmd
index 3cf324a1a..6a2427c39 100644
--- a/docs/output-formats/typst-custom.qmd
+++ b/docs/output-formats/typst-custom.qmd
@@ -54,7 +54,7 @@ Additional resources you might find useful when creating custom formats include:
 
 ## Book Format Extensions
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 A Typst book format extension includes template partials that configure the underlying Typst package, and a Lua filter that transforms Quarto's book structure into package-specific commands. The core partials are:
 
diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd
index 8a78f15fd..a3e1f088f 100644
--- a/docs/output-formats/typst.qmd
+++ b/docs/output-formats/typst.qmd
@@ -219,7 +219,7 @@ This gets compiled to
 
 ## Theorems
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 Quarto uses the [theorion](https://typst.app/universe/package/theorion) package for theorems in Typst output. You can control the appearance of theorems, lemmas, proofs, and related blocks using the `theorem-appearance` option:
 
diff --git a/docs/publishing/posit-connect-cloud.qmd b/docs/publishing/posit-connect-cloud.qmd
index 9d23f5112..9a45ac880 100644
--- a/docs/publishing/posit-connect-cloud.qmd
+++ b/docs/publishing/posit-connect-cloud.qmd
@@ -14,7 +14,7 @@ provider:
         default web browser, then press Enter or 'Y' to authorize.
 ---
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 ## Overview
 
diff --git a/docs/websites/website-search.qmd b/docs/websites/website-search.qmd
index 0293e7fcb..9abb9a1a1 100644
--- a/docs/websites/website-search.qmd
+++ b/docs/websites/website-search.qmd
@@ -83,7 +83,7 @@ When you click a search result, Quarto navigates to the destination page and hig
 
 The highlighting is driven by a `?q=` URL parameter. You can manually add `?q=term` to any page URL to highlight occurrences of that term — useful for sharing links that draw attention to specific content.
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 Highlights remain visible until you navigate away from the page. When a match is found inside a [tabset](/docs/output-formats/html-basics.qmd#tabsets), the correct tab is automatically activated to reveal the highlighted content, including nested and grouped tabsets. Multi-word search terms are highlighted correctly even when they span across formatting boundaries such as bold, italic, code spans, or syntax-highlighted code blocks.
 

From a944e3b0e844f941af54aa3660fc6de42a1e6736 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 11 Mar 2026 21:19:25 +0100
Subject: [PATCH 7/7] Replace missed _pre-release-feature include in syntax
 highlighting doc

---
 docs/output-formats/_document-options-syntax-highlighting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/output-formats/_document-options-syntax-highlighting.md b/docs/output-formats/_document-options-syntax-highlighting.md
index 745457697..85414b566 100644
--- a/docs/output-formats/_document-options-syntax-highlighting.md
+++ b/docs/output-formats/_document-options-syntax-highlighting.md
@@ -2,7 +2,7 @@
 
 ::: {.content-visible when-meta="doc-type.typst"}
 
-{{< include /docs/prerelease/1.9/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.9 >}}
 
 :::