Backport five accessibility fixes to prerelease (#2271)

* Fix skipped heading levels in markdown headings (#2227)

* Heading order fixes

* Remove extra h1 and reflow

* Fix headings that should have been "captions"

* Update freeze

(cherry picked from commit c56f6cb)

* Fix contrast of the extensions chooser and listing description links (#2235)

* Use the theme link color for the extensions category chooser

The chooser tiles hard-coded #5092dd, which is 3.23:1 on white (WCAG 1.4.3 needs 4.5:1). var(--bs-link-color) gives 5.15:1 in light mode and 7.27:1 in dark mode. Clears axe color-contrast-0f9515 (20 instances on 5 pages).

* Underline links in listing-table descriptions

Quarto's listing-table styles remove link underlines, so description links rely on color alone: 2.23:1 against body text, short of the 3:1 WCAG 1.4.1 needs. Clears axe link-in-text-block-82c7eb and the extensions-page instances of link-in-text-block-7b0c90.

(cherry picked from commit e26940f)

* Make the tool choosers consistent (#2258)

* Make the tool choosers consistent with a shared page-chooser shortcode

* Use --bs-border-color for chooser tiles in light mode

(cherry picked from commit dab304a)

* Close the listing-link rule so the visually-hidden code rule applies again (#2257)

#2235 left out the closing brace of the listing-description link rule.
Browsers then read the #2234 rule for screen-reader-only code blocks as a
nested rule that never matches, and the blocks became scrollable regions
again (axe scrollable-region-focusable).

(cherry picked from commit 6f27b3f)

* fix(a11y): give embedded videos an iframe title (#2141)

Screen readers announce an iframe by its title. The video shortcode
emits title="" when the author omits the title argument, so these two
embeds failed axe's frame-title check (serious, WCAG 2.0 A, SC 4.1.2).

Add title="CERN: The Journey of Discovery" to the two live {{< video >}}
calls, and to the escaped copies the same pages display as source, so
the shown example matches the rendered output. In tables.qmd the call
sits inside a data-qmd="..." attribute, so the title uses single quotes.

(cherry picked from commit ccf7a9e)

Author: cwickham

.claude/rules/docs-authoring.md

@@ -22,3 +22,7 @@ When referring to a Quarto format by its identifier (the value used in `format:`
 ## Toolbar icons
 
 Refer to a UI control by its name in bold, then "button" if it is one, then the icon as a decorative image: `**Render** button ![](images/rstudio-render-button.png){.ui-icon alt="" width="25" height="20"}`. Never wrap icons or control names in `<kbd>` (it is for keyboard input, and `kbd.js` uppercases one-word `<kbd>` text on macOS). Never leave an icon as the only name for a control. Use the name the control itself exposes (label, tooltip, or accessible name). See the "Toolbar Icons" section of `_style-guide.md`.
+
+## Headings and example labels
+
+Use a heading only to start a section, and never skip a level. A label for one example ("Markdown Syntax", "Output", "HTML output", a theme name under a screenshot) is a caption, not a heading. Label code blocks with `filename="..."`, images with a caption (plus `fig-cap-location: top` for a sequence of images), output with a lead-in sentence ("This renders as:"), and source/output pairs with a table. A bold paragraph is the fallback. Never use `{.unlisted}` headings as captions. When you fix an axe `heading-order` finding, first decide if the skipped heading is a real section. If it is a caption, replace it; do not change its level. See the "Headings and Example Labels" section of `_style-guide.md`.

_extensions/page-chooser/_extension.yml

@@ -0,0 +1,7 @@
+title: Page chooser
+author: Quarto
+version: 1.0.0
+quarto-required: ">=1.9.0"
+contributes:
+  shortcodes:
+    - page-chooser.lua

_extensions/page-chooser/page-chooser.css

@@ -0,0 +1,69 @@
+/* page-chooser: plain CSS using Bootstrap custom properties, so it works in
+   light and dark themes and can be renamed to an SCSS partial unchanged. */
+
+.page-chooser {
+  margin-bottom: 1rem;
+}
+
+/* The dark theme's --bs-border-color is near-invisible (1.08:1), so keep
+   #2237's border until the theme's $border-color is fixed. Light mode uses
+   --bs-border-color as is. */
+body.quarto-dark .page-chooser {
+  --page-chooser-border: #6c757d;
+}
+
+.page-chooser .page-chooser-label {
+  margin-top: 1rem;
+  margin-bottom: 0.25rem;
+}
+
+.page-chooser .page-chooser-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.page-chooser .page-chooser-list a {
+  display: block;
+  width: var(--page-chooser-item-width, 102px);
+  height: 100%;
+  padding: 0.5rem 0.25rem;
+  text-align: center;
+  font-size: 0.8em;
+  color: var(--bs-body-color);
+  text-decoration: none;
+  border: 1px solid var(--page-chooser-border, var(--bs-border-color));
+  border-radius: 10px;
+}
+
+.page-chooser .page-chooser-list a:hover {
+  border-color: var(--bs-link-color);
+}
+
+.page-chooser .page-chooser-list a[aria-current="page"] {
+  font-weight: 600;
+  border-color: var(--bs-link-color);
+  box-shadow: inset 0 0 0 1px var(--bs-link-color);
+}
+
+.page-chooser .page-chooser-list img {
+  display: block;
+  width: 65px;
+  height: 65px;
+  margin: 0 auto 2px;
+}
+
+.page-chooser .page-chooser-list .bi {
+  display: block;
+  font-size: 3rem;
+  line-height: 1;
+  margin-bottom: 5px;
+  color: var(--bs-link-color);
+}
+
+.page-chooser .page-chooser-list .text-editor-logo {
+  opacity: 0.7;
+}

_extensions/page-chooser/page-chooser.js

@@ -0,0 +1,17 @@
+// Mark the link to the current page and remember it, for every .page-chooser.
+(function () {
+  const filename = window.location.pathname.split("/").slice(-1)[0];
+  for (const chooser of document.querySelectorAll(".page-chooser")) {
+    const isIndex = filename === "" || filename === "index.html";
+    const target = isIndex && chooser.dataset.default ? chooser.dataset.default : filename;
+    for (const link of chooser.querySelectorAll("a")) {
+      if (target && link.pathname.split("/").slice(-1)[0] === target) {
+        link.setAttribute("aria-current", "page");
+        break;
+      }
+    }
+    if (chooser.dataset.storageKey && filename) {
+      window.localStorage.setItem(chooser.dataset.storageKey, filename);
+    }
+  }
+})();

_extensions/page-chooser/page-chooser.lua

@@ -0,0 +1,87 @@
+-- page-chooser: a labelled row of links to sibling pages ("Choose your tool").
+--
+-- Usage:  {{< page-chooser tools >}}
+--
+-- Reads `page-choosers.<name>` from document metadata (usually a directory
+-- _metadata.yml):
+--
+--   page-choosers:
+--     tools:
+--       label: Choose your tool          # visible label; also names the <nav>
+--       storage-key: tutorialToolGetStarted  # optional: remember the last page
+--       default: listing-filters.html    # optional: item marked current on index.html
+--       item-width: 147px                # optional: tile width (default 102px)
+--       items:
+--         - text: Positron
+--           href: positron.html
+--           img: ../images/positron-logo.svg   # decorative logo, or
+--           icon: gear                          # a Bootstrap icon name
+--           icon-class: text-editor-logo        # optional extra class on the logo
+
+local function str(v)
+  if v == nil then return nil end
+  return pandoc.utils.stringify(v)
+end
+
+local function esc(s)
+  return (s:gsub("&", "&amp;"):gsub("<", "&lt;"):gsub(">", "&gt;"):gsub('"', "&quot;"))
+end
+
+local function attr(name, value)
+  if value == nil or value == "" then return "" end
+  return " " .. name .. '="' .. esc(value) .. '"'
+end
+
+return {
+  ["page-chooser"] = function(args, kwargs, meta)
+    if not quarto.doc.is_format("html") then
+      return pandoc.Null()
+    end
+
+    local name = str(args[1])
+    local choosers = meta["page-choosers"]
+    local cfg = name and choosers and choosers[name]
+    if cfg == nil then
+      quarto.log.warning("page-chooser: no `page-choosers." .. tostring(name) .. "` in metadata")
+      return pandoc.Null()
+    end
+
+    quarto.doc.add_html_dependency({
+      name = "page-chooser",
+      version = "1.0.0",
+      stylesheets = { "page-chooser.css" },
+      scripts = { { path = "page-chooser.js", afterBody = true } },
+    })
+
+    local label_id = name .. "-chooser-label"
+    local width = str(cfg["item-width"])
+    local style = width and ("--page-chooser-item-width: " .. width) or nil
+
+    local out = {}
+    table.insert(out, '<div class="page-chooser"' ..
+      attr("data-storage-key", str(cfg["storage-key"])) ..
+      attr("data-default", str(cfg["default"])) .. '>')
+    table.insert(out, '<p class="page-chooser-label h3"' .. attr("id", label_id) .. '>' ..
+      esc(str(cfg.label) or "") .. '</p>')
+    table.insert(out, '<nav' .. attr("aria-labelledby", label_id) .. '>')
+    table.insert(out, '<ul class="page-chooser-list"' .. attr("style", style) .. '>')
+    for _, item in ipairs(cfg.items or {}) do
+      local logo = ""
+      if item.img then
+        logo = '<img' .. attr("src", str(item.img)) .. ' alt=""' ..
+          attr("class", str(item["icon-class"])) .. '>'
+      elseif item.icon then
+        logo = '<i class="bi bi-' .. esc(str(item.icon)) ..
+          (item["icon-class"] and (" " .. esc(str(item["icon-class"]))) or "") ..
+          '" aria-hidden="true"></i>'
+      end
+      table.insert(out, '<li><a' .. attr("href", str(item.href)) .. '>' ..
+        logo .. esc(str(item.text) or "") .. '</a></li>')
+    end
+    table.insert(out, '</ul>')
+    table.insert(out, '</nav>')
+    table.insert(out, '</div>')
+
+    return pandoc.RawBlock("html", table.concat(out, "\n"))
+  end
+}