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

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`.

_freeze/docs/authoring/tables/execute-results/html.json

@@ -708,6 +708,7 @@ format:
 filters:
   - filters/tools-tabset.lua
   - filters/color-box.lua
+  - filters/shift-headings.lua
   - at: post-quarto
     path: filters/include-dark.lua
 

_freeze/docs/computations/execution-options/execute-results/html.json

@@ -101,3 +101,36 @@ Use the **Render** button ![](images/rstudio-render-button.png){.ui-icon alt=""
 ```
 
 The `.ui-icon` class (`theme.scss` and `theme-dark.scss`) gives the image the same key-cap look as `<kbd>` in the light and dark themes.
+
+## Headings and Example Labels
+
+Use a heading only when it starts a section. A section continues until the next heading of the same level or higher. Screen readers use headings to move through a page, and the page TOC lists them.
+
+Do not skip heading levels. After `##`, the next level is `###`.
+
+A short label for one example is a caption, not a heading. Labels such as "Markdown Syntax", "Output", "HTML output", and "Arrow (light)" are captions. If you use a heading for a caption, the text after the example becomes part of the caption's section. This is incorrect when that text applies to the whole section.
+
+Use one of these patterns for a caption:
+
+* For a code block, use the `filename` attribute. The label shows in the header of the block.
+
+  ````markdown
+  ``` {.markdown filename="Markdown Syntax"}
+  | Right | Left |
+  |------:|:-----|
+  ```
+  ````
+
+* For an image, use the image caption. The caption becomes a `<figcaption>` for the image. If a page shows several captioned images in a sequence, set `fig-cap-location: top` in the page front matter. Then each caption is directly above its image.
+
+  ```markdown
+  ![Arrow (light)](images/arrow.png){fig-alt="A block of code showcasing the Arrow (light) theme."}
+  ```
+
+* For rendered output that follows its source, write a lead-in sentence, for example "This renders as:".
+
+* For a set of source and output pairs, use a table with `Markdown Syntax` and `Output` column headers. See "Other Blocks" in `docs/authoring/markdown-basics.qmd`.
+
+* For output that has no other pattern, use a bold label paragraph, for example `**PDF output**`.
+
+Do not add `{.unlisted}` to a heading to hide a caption from the TOC. The heading is still in the page structure.