diff --git a/.github/workflows/verify.yaml b/.github/workflows/verify.yaml
index 67eec2eb93af..57df54442408 100644
--- a/.github/workflows/verify.yaml
+++ b/.github/workflows/verify.yaml
@@ -20,6 +20,12 @@ jobs:
# Set to true when we want to start having errors fail the pipeline.
fail_on_error: true
+ # Pin the Vale version. 3.22.0 regressed inline-HTML/markdown-link
+ # tokenization (concatenating adjacent words into single tokens,
+ # e.g. "Publishedon" -> "Publishedon"), failing the
+ # build on long-unchanged content. Bump intentionally.
+ version: 3.21.0
+
# Only check lines touched by the PR to avoid reviewdog's
# "too many annotations" failures on full-corpus scans.
filter_mode: added
diff --git a/assets/css/custom.css b/assets/css/custom.css
index 8702f532d488..db547fa84bf1 100644
--- a/assets/css/custom.css
+++ b/assets/css/custom.css
@@ -332,12 +332,20 @@ p.egg {
}
/* --- Generated config reference page (docs/deployment/references) ---
- The item comments read as normal prose; each config item is the
- code-font element on an unshaded bordered card, so the key/value lines
- stand out from the comments around them without dual grey shading. */
+ Each config item and its documentation comment are wrapped together in
+ a .ref-block div. The item renders as a code-font bordered card with
+ the key/breadcrumb/value as code; its comment reads as normal prose
+ beside the key, so key/value lines stand out without dual grey
+ shading. Leaf comments sit under the card; container comments sit
+ inside the right under the key row so they stay put. */
+.ref-block {
+ display: block;
+ margin: 0 0 1rem 0;
+}
+
.item-comment {
font-family: var(--hx-font-sans);
- margin: 16px 0 6px 0;
+ margin: 6px 0 0 0;
color: inherit;
}
@@ -359,6 +367,7 @@ p.egg {
display: flex;
align-items: center;
padding-right: 1ex;
+ font-weight: 700;
}
/* Example values: same indent as the key/breadcrumb above them so the
@@ -407,9 +416,17 @@ p.egg {
list-style: none;
cursor: pointer;
display: flex;
+ flex-wrap: wrap;
align-items: center;
}
+/* A container's own comment lives inside the summary right under its key
+ row, so it stays "under the ref-item" on every line regardless of
+ expansion depth. Force it to its own line below the key. */
+.reference-document details > summary .item-comment {
+ flex-basis: 100%;
+}
+
.reference-document details > summary::-webkit-details-marker {
display: none;
}
@@ -434,6 +451,9 @@ p.egg {
padding: 0.5rem 0.75rem;
margin: 0 0 0.5rem 0;
transition: border-color 0.2s ease, background-color 0.2s ease;
+ /* Anchor targets: offset item cards below the sticky top navbar when a
+ shared #fragment link is opened, so the item is not hidden under it. */
+ scroll-margin-top: calc(var(--navbar-height) + 1rem);
}
.dark .ref-item {
@@ -472,11 +492,9 @@ p.egg {
max-width: 30em;
}
-/* Filtered-out items are hidden; containers that match stay expanded.
- The item's associated comment block hides with it (the filter toggles
- filtered-out on both; see references/reference-filter script). */
-.ref-item.filtered-out,
-.item-comment.filtered-out {
+/* Each config item and its documentation comment are wrapped in one
+ .ref-block div, so hiding a block hides both. */
+.ref-block.filtered-out {
display: none;
}
@@ -782,6 +800,14 @@ html.dark .hextra-nav-btn[aria-current] {
--hextra-max-page-width: 84rem;
--hextra-max-navbar-width: 84rem;
--hextra-max-footer-width: 84rem;
+ /* The theme's static default --hextra-banner-height: 2rem is smaller than
+ the real banner (its h-10 close button makes it 2.5rem tall), and the
+ theme only re-measures that variable in deferred core/banner.js. Pre-set
+ the correct height here so first paint is already right and the floating
+ TOC chevrons (which offset by this variable) don't jump once the script
+ runs. When the banner is dismissed, head/banner.js sets the variable to
+ 0 inline before paint, which overrides this default. */
+ --hextra-banner-height: 2.5rem;
}
@media (min-width: 768px) {
@@ -1234,82 +1260,42 @@ html.dark #pagefind-site-search .pagefind-ui__result-tag {
margin-left: 0.375rem;
}
-/* --- Pagefind filter panel (/search/ page) ---
- Once the index carries data-pagefind-filter values, the old PagefindUI
- renders a checkbox sidebar (fieldset.pagefind-ui__filter-panel) next to
- the results. On this site the /search/ column (~768px) wraps the drawer,
- so the panel renders as a collapsible "Section" accordion above the
- results - style it as such (border-bottom, no right rules). */
-#pagefind-site-search .pagefind-ui__filter-panel {
- margin-top: 1rem;
-}
-#pagefind-site-search .pagefind-ui__filter-panel-label {
- font-size: 0.75rem;
- font-weight: 700;
- text-transform: uppercase;
- letter-spacing: 0.05em;
- color: var(--hx-color-neutral-500, #737373);
-}
-#pagefind-site-search .pagefind-ui__filter-block {
- border-bottom: 1px solid var(--hx-color-neutral-200, #e5e5e5);
-}
-#pagefind-site-search .pagefind-ui__filter-name {
- font-size: 0.875rem;
- font-weight: 600;
- color: var(--hx-color-neutral-900, #171717);
-}
-html.dark #pagefind-site-search .pagefind-ui__filter-name {
- color: var(--hx-color-neutral-100, #f5f5f5);
-}
-#pagefind-site-search .pagefind-ui__filter-group {
- gap: 0.625rem;
- padding-top: 0.875rem;
-}
-#pagefind-site-search .pagefind-ui__filter-value {
- display: flex;
- align-items: center;
- gap: 0.5rem;
-}
-#pagefind-site-search .pagefind-ui__filter-label {
- font-size: 0.875rem;
- color: var(--hx-color-neutral-700, #404040);
-}
-html.dark #pagefind-site-search .pagefind-ui__filter-label {
- color: var(--hx-color-neutral-300, #d4d4d4);
-}
-#pagefind-site-search .pagefind-ui__filter-checkbox {
- border: 1px solid var(--hx-color-neutral-300, #d4d4d4);
- background-color: transparent;
- border-radius: 4px;
-}
-#pagefind-site-search .pagefind-ui__filter-checkbox:checked {
- background-color: var(--hx-color-primary-600, #2563eb);
- border-color: var(--hx-color-primary-600, #2563eb);
-}
-
-/* The search modal keeps the tag chips but not the filter sidebar
- (filtering is a /search/ page feature). */
+/* --- /search/ page: native Pagefind filter panel is hidden ---
+ PagefindUI renders a checkbox "Section"/"Tags" filter panel per query once
+ the index carries data-pagefind-filter values. On this site the /search/
+ column (~768px) would wrap it next to the results, and the shortcode already
+ renders its own server-side "Filter by Section" / "Filter by Tag"
+ accordions (visible before any query is typed). The native panel is
+ therefore hidden and used only as a source of truth: search.js reads its
+ per-value counts to prune the accordion pills and toggles its checkboxes
+ on pill click. The search modal keeps the tag chips but not the filter
+ sidebar (filtering is a /search/ page feature). */
+#pagefind-site-search .pagefind-ui__filter-panel,
#pagefind-ui .pagefind-ui__filter-panel {
display: none;
}
+/* The native filter blocks are left in the DOM (search.js reads their
+ counts) but must never paint. */
+#pagefind-site-search .pagefind-ui__filter-block[hidden] {
+ display: none !important;
+}
-/* --- /search/ page: "Tags" accordion (shortcode renders the same
- taxonomy listing as the /tags/ page; search.js moves it into the
- filter panel, under the Section block). The svelte-scoped pagefind
- rules don't cover this element, so it needs its own chrome here.
- The rules are scoped to the element id so they apply both before the
- search (as a sibling of the PagefindUI mount) and once it is moved
- into the filter panel; id specificity also beats the pagefind
- `.pagefind-ui--reset * { all: unset }` inside the UI root. */
+/* --- /search/ page: "Filter by Section" and "Filter by Tag" accordions
+ (shortcode renders both, with the full server-side lists, so they are
+ visible before any query). The pagefind rules don't cover these elements,
+ so they need their own chrome here. The rules are scoped to the element
+ ids so they apply independently of the PagefindUI mount; id specificity
+ also beats the pagefind `.pagefind-ui--reset * { all: unset }`. */
+#pagefind-site-sections,
#pagefind-site-tags {
cursor: default;
margin-top: 0.75rem;
}
-/* Inside the panel, the filter-panel already carries margin-top —
- reset so the accordion sits flush under the Section block. */
-#pagefind-site-search .pagefind-ui__filter-panel #pagefind-site-tags {
- margin-top: 0;
+/* Keep the accordions visually separate from the PagefindUI input below. */
+.search-box[data-site-search] #pagefind-site-search {
+ margin-top: 1rem;
}
+#pagefind-site-sections .search-sections-name,
#pagefind-site-tags .search-tags-name {
position: relative;
cursor: pointer;
@@ -1321,14 +1307,18 @@ html.dark #pagefind-site-search .pagefind-ui__filter-label {
font-weight: 600;
color: var(--hx-color-neutral-900, #171717);
}
+html.dark #pagefind-site-sections .search-sections-name,
html.dark #pagefind-site-tags .search-tags-name {
color: var(--hx-color-neutral-100, #f5f5f5);
}
+#pagefind-site-sections .search-sections-name::-webkit-details-marker,
+#pagefind-site-sections .search-sections-name::marker,
#pagefind-site-tags .search-tags-name::-webkit-details-marker,
#pagefind-site-tags .search-tags-name::marker {
display: none;
}
/* Same disclosure chevron as the Section blocks (border triangle). */
+#pagefind-site-sections .search-sections-name::after,
#pagefind-site-tags .search-tags-name::after {
content: "";
position: absolute;
@@ -1341,21 +1331,29 @@ html.dark #pagefind-site-tags .search-tags-name {
border-top: 0;
transform: translateY(-70%) rotate(-45deg);
}
+#pagefind-site-sections[open] .search-sections-name::after,
#pagefind-site-tags[open] .search-tags-name::after {
transform: translateY(-70%) rotate(-225deg);
}
-/* Tag cloud: the panel column is narrow, so wrap instead of the /tags/
+/* Pill clouds: the panel column is narrow, so wrap instead of the /tags/
page's multi-column grid. */
+#pagefind-site-sections .search-sections-grid,
#pagefind-site-tags .search-tags-grid {
display: flex;
flex-wrap: wrap;
gap: 0.25rem 1.5rem;
padding-top: 0.875rem;
}
-/* Filter-toggle pills in the /search/ Tags accordion.
- Originally styled for elements; now rendered as