Findability - prototype - Hub pages

[florent-leborgne]

Prototype for the docs Findability initiative -- workstream 2C (Hub Pages). Stacked on top of #2927 (nav-v2) and #3133 (nav-v2-sections), so review there first.

Important

This PR pairs with the hub-pages branch of elastic/docs-content. The assembler config (config/assembler.yml, narrative.current: hub-pages) clones that branch as the narrative source, so the docs-builder side and the docs-content side build together. Either both land, or both stay paired during review.

Thanks to @theletterf for landing the V2 nav-island wiring upstream, which is what made it possible to render real hub pages through the assembler and remove the gist-preview workaround.

Design handoff: hub-pages-design-handoff gist -- UX choices, technical notes, and what's open for proper design to refine.

What it does

Adds first-class support for product hub pages -- product-scoped 360° landing pages -- to docs-builder. A regular markdown page becomes a hub page by setting layout: hub in frontmatter; the body is then composed from a small set of new MyST directives. Companion docs-content hub-pages branch adds the actual hub markdown for Elasticsearch and Kibana at /products/<product>/v9/.

Alongside the hub layout, this PR reworks the page-top metadata model so pills (navigation) and applies_to (page-level requirements) coexist cleanly without piling loose badges at the top of every page.

What landed

New frontmatter layout

layout: hub	New MarkdownPageLayout.Hub enum value. Selects _Layout.cshtml's RenderHub() branch -- same chrome as default minus the right-rail TOC and prev/next nav. The body owns the full content-column width so directives can render full-bleed sections.

New directives (under Elastic.Markdown.Myst.Directives.Hub/)

Directive	Purpose
{hero}	Full-bleed dark-navy hero band. Explicit options: :icon:, :title:, :description:, :releases:. Inline product-icon SVGs for elasticsearch/kibana/observability/security, with single-letter fallback. Auto-renders a muted eyebrow above the title: a "Find all docs about {title}" label (signals the page is a documentation index) next to a "Browse all Elastic docs" pill link to the docs home, as an escape hatch to the full docs for readers who landed here looking for something broader.
{on-this-page}	Auto-generated inline TOC chip -- collects every {card-group} and {whats-new} on the page that has both id and title. Sticky on desktop so it stays visible while scrolling.
{intro}	Small "getting started" callout panel with a teal accent bar. Body = inline markdown.
{whats-new}	"What's new" panel. Centralized lookup via :product: from a single source-of-truth config/whats-new.yml (any page can render any product's panel with one line); inline YAML body still works as override.
{card-group}	Section heading + card grid container. Options: :title:, :intro:, :id:.
{link-card}	Rich card. YAML body with a fixed schema -- title, link, description, links[], aside, plus optional icon/variant for solution-style accent borders.

Note

The hero was deliberately pared back to icon, title, description, and the latest-release line. The earlier search field, version dropdown, and quick-link pills were removed to keep the band clean -- discovery happens through the page body and the top-bar nav rather than hero controls.

The eyebrow (the "Find all docs about {title}" label + "Browse all Elastic docs" link) is a lightweight working baseline. The wording, placement, link target, and styling should be reviewed and refined during proper design -- see the design handoff gist.

Page-top metadata: single "This page applies to" box

The page top is now a single labeled container (Page/MetadataBox.cshtml) rendered below the H1 on regular pages. Stacking pills + applies_to badges loose at the page top would be a noisy, unstructured strip; the box gives both systems an explicit place and frees room for future page-level metadata (e.g. licensing).

Title row: The bold "This page applies to" label, with product hub pills rendered next to it (one per products: frontmatter entry whose product has hub: set in config/products.yml). Pills carry a brand-color dot, the product name, and a → arrow. They're nav affordances, not body links -- styled dark-grey + semi-bold + no underline (override of .markdown-content a).

Below the title row: applies_to-driven rows, separated by a thin divider. Native <details open> makes the rows collapsible (chevron at far right of the title row, expanded by default).

Row	Content
Versions	applies_to.stack entries, plus applies_to.serverless iff no deployment is specified.
Deployments	applies_to.deployment entries, plus applies_to.serverless iff a deployment is specified (so Serverless lands in only one row).

Entries render as plain comma-separated text with a small ? icon after each value (CSS-only reskin of the existing <applies-to-popover> -- the rich tooltip behavior is preserved on hover/click). Items are sorted with Serverless first, then other available items, then unavailable items at the end (struck-through and dimmed).

Three new ApplicabilityBadgePlacement modes (StackVersionsRow, DeploymentsRow, OtherProductsRow) drive the per-row collection logic.

Tooltip copy: Stack and Serverless product descriptions in ProductDescriptions.cs were updated. The Stack description uses {base} / {current} / {base-major} placeholders interpolated from the VersioningSystem at render time (e.g. "This documentation applies to Elastic Stack 9.0.0 to 9.4.0...") so it tracks versions.yml. Serverless descriptions append a sentence noting that Serverless UI/capabilities can differ from versioned Elastic Stack.

Note

The current visual language (pill shape, grey-tinted box, divider, chevron position, "?" icon) is a working baseline so we can reason about layout. Final styling, spacing, and placement are for proper design to refine -- see the design handoff gist for the rationale and what's open for iteration.

Centralized "What's new" feed

• config/whats-new.yml (embedded as a resource so the binary always carries it).
• Loaded through ConfigurationFileProvider (WhatsNewFile property) and exposed via BuildContext -- the same pattern used by products.yml.
• Schema: products.<key> -> { title, id, badge, release-links[], items[] }.

Page-title detection

• MarkdownFile.cs falls back to descendant H1s if no top-level H1 is found, then to {hero}'s :title: option. Hub pages can therefore be purely directive-driven (no body H1) and still get correct page titles.

Navigation

• config/navigation-v2.yml: new Products top-bar section in the second slot (right after Guides). The section uses a new dropdown: true opt-in that renders it as a top-bar dropdown. For the prototype it lists a single Stack products group with Elasticsearch and Kibana -- the only products that currently have hub pages. (The dropdown supports - label: subsection grouping and muted "soon" stubs for - title: items, but none are used here yet.) No /products/ landing page -- the dropdown is the discovery surface.
• New top-bar dropdown feature (opt-in via dropdown: true on a section): adds a Dropdown flag through SectionNavV2Item → SectionNavigationNode → NavigationSection, and Layout/_SecondaryNav.cshtml renders the section as a <details>/<summary> with a chevron + menu when set. Styled by Assets/secondary-nav-dropdown.css: the menu is hidden when closed and anchored under its summary, and the nav scroll container's overflow opens up while a dropdown is expanded so the menu isn't clipped behind the left nav. The summary is a non-clickable <span> so the whole row toggles the dropdown.
• _Layout.cshtml's hub branch puts the content <main> in the wide column (md:order-2) next to the pages-nav sidebar, and includes an empty <aside id="toc-nav" hidden> so htmx-boosted swaps from regular pages (which select #content-container,#toc-nav) don't bail when navigating into a hub. Hub pages have their own inline {on-this-page} chip, so the slot stays empty.
• config/products.yml: Product.Hub field set to relative slugs (products/elasticsearch/v9, products/kibana/v9) so pills resolve against the site path prefix.
• Product pills opt out of hx-boost (the body-level htmx default) so click → full native navigation; otherwise htmx swallowed the click before navigation.

Source location

• Hub markdown lives in docs-content at products/{elasticsearch,kibana}/v9.md (on the hub-pages branch).
• URL convention: /products/<product>/<major>/ -- e.g. v9, v8. v9+ is cumulative for v9 minors and Serverless, so a single hub covers the active surface.

Styling

• New src/Elastic.Documentation.Site/Assets/markdown/hub.css and metadata-box.css, modeled on the visual prototype, using docs-builder design tokens. Imported from styles.css.
• Hero icon-aligned-with-H1 layout via CSS Grid + display: contents.
• The top-bar Products dropdown uses a native <details>/<summary> (no JS).
• Cards and "What's new" rows use grid layouts so columns line up across rows.

Documentation

• 7 new pages under docs/syntax/:
  • hub-pages.md -- overview + skeleton + product-badge mapping
  • hero.md, whats-new.md, intro.md, on-this-page.md, card-group.md, link-card.md
• All wired into _docset.yml alphabetically.

How to preview

Preview builds are published automatically for this PR. Open:

• Elasticsearch hub page.
• Kibana hub page.
• Assembler preview root.

The hub pages render through the assembler preview at their target URL shape (/products/<product>/<major>/), so no local isolated or assembler build is required for review.

Known limitations

• {link-card} URLs bypass crosslink validation. Because the card body is YAML, the URLs inside links[] and aside.links[] aren't seen by the markdown link-validator. They'll render and click, but typos won't fail the build. Worth re-evaluating before this becomes a content authoring path beyond the prototype.

• {hero} directive emits :releases: URLs verbatim. The hero's inline :releases: values don't go through docs-builder's cross-link or .md-path resolver, so authors have to write full elastic.co URLs there rather than <repo>://... or /path.md. Worth fixing in the directive so authors can use the same conventions everywhere.

• No tests. No unit/snapshot tests for the new directives, view models, page-title fallback, metadata box, or top-bar dropdown. Should land before promoting to non-prototype.

Out of scope (per the original Findability plan, by design)

• Dynamic v9 hub generation from metadata.
• Versioned hubs other than the v9 prototype.
• Hub-internal "What's new" auto-population from {changelog} bundles.
• Final visual design of the page-top metadata model (pills + Availability box) -- structure landed; styling refinement is for proper design.

🤖 Generated with Claude Code