Hub pages 1/4: hub page layout and the {hero} directive

[florent-leborgne]

Part 1 of 4. Implements elastic/docs-content-internal#1386 (layout: hub) and #1380 ({hero}), against the promotion bar in #1379.

Demo: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3825/examples/products/docs-builder

Rebuilt on the current navigation implementation. The prototype branch is merged with nav-v2, which is out of scope, so nothing from nav-v2 ports.

What this adds

• MarkdownPageLayout.Hub and the RenderHub branch. It drops the right-rail table of contents and the previous/next navigation, keeps the left sidebar, and gives the body the full content column.
• Page-title detection falls back from a top-level H1, to an H1 nested in a directive, to {hero}'s :title:. A hub page has no authored H1.
• {hero}: product icon, page title, description, and up to three optional actions.
• A page with layout: hub and no {hero} fails the build. The layout removes the page H1, so the page would otherwise have no title.
• docs/syntax/hub-pages.md, docs/syntax/hero.md, an example hub at docs/examples/products/docs-builder.md, and F# authoring tests.

Visual decisions

• Hero actions use the {button} directive's neutral style from feat(button): add neutral variant to the button directive #3853. All three carry equal weight, so the option names set order, not prominence. A blue variant would make each action claim to be the call to action.
• The eyebrow border moves to grey-70. feat(button): add neutral variant to the button directive #3853 flagged that this stack used border colours failing the 3:1 non-text contrast ratio, and the border is what identifies that control.
• All hub text uses the site's size tokens. Body text is 16px and nothing renders below 14px.
• An arrow marks only a link that sends the reader onward, never a button. One shared class draws it.
• The hero adds no side padding of its own, so it lines up with every section on the page at any width.

Implementation choices

DirectiveLinkValidator. Directive links never reach Markdig's inline link parser, so every directive taking a URL had invented its own handling. This promotes the prototype's hub-only validator to a shared one and moves {page-card} onto it, deleting its hand-rolled copy. {page-card} keeps its contract: relative links resolve against the source file, and no file-existence check runs, because its links can target generated pages such as the CLI reference.

Parser guard. DirectiveBlockParser.TryContinue stops an ancestor directive consuming an option line once it has opened a nested directive child. Without it the ancestor takes every descendant's options and the last one wins.

The collision only fires when a parent and child read the same option name. Only the hub pair overlaps: {explore} and {card-group} both use :id: and :title:. Existing pairs split cleanly, so they were latently exposed but never broken.

Parent	reads	Child	reads
{tab-set}	group	{tab-item}	sync, selected
{applies-switch}	group	{applies-item}	sync
{stepper}	none	{step}	anchor
{dropdown}	open	{note}	name

tests/authoring/Blocks/NestedDirectiveOptions.fs pins that each option still reaches the block that declared it, for all four pairs. Those tests pass with the guard removed, so they are guard-rails against breaking option routing rather than regression tests for the bug itself. The {explore} tests in #3826 are what catch the bug.

The guard changes exactly one pattern: an option line appearing after a nested child has opened. A scan of every markdown file in docs-builder and docs-content found zero occurrences.

Cross-links are not external. A cross-link resolves to a full URL but still points at documentation this site serves, so it does not open in a new tab. Inline links make the same distinction.

Machine-readable output. {hero} gets an LLM renderer and a plain-text renderer. The search body takes the hero title and description only. Indexing section and card titles would let a hub outrank the pages it links to.

Article id, not class. The article keeps id="markdown-content", which the copy button, syntax highlighter and smooth scroll select on. It does not take the class: typography.css is unlayered and hub.css sits in @layer components, so the class would override every hub rule.

Two prototype details do not port. The empty #toc-nav slot is dropped, because main replaced hx-select-oob with a whole-body swap. Hero links use preload rather than hx-boost="false", matching PageCardView.

Known gaps

• No version switcher on a hub page. VersionDropdown renders from the table-of-contents rail this layout removes. The designs place it in the top bar, which belongs to the navigation work in elastic/docs-content-internal#1589.
• :description: uses the default Markdig pipeline, because it is a directive option rather than a body block. Substitutions, roles and link validation do not apply inside it. Documented on the syntax page.

Testing

./build.sh unit-test passes. dotnet format and npm run fmt:check are clean. A full docs build reports 0 errors and 0 warnings.

Adds containsRawHtml and doesNotContainHtml to the authoring assertions. The pretty-printed comparison only matches a childless element or a snapshot taken from the outermost element of the directive output, so asserting an attribute on a container needs the raw form.

Screenshots to add or update

None attached. Check the rendered hero on the preview.

[theletterf]

Nice! Two Qs:

• How does a hub page render without a hero directive? Should it trigger an error if empty?
• Related to the above, do we want to keep hero directives independent and available to all pages? Shouldn't the hero block, if mandatory for all hub pages, be part of the layout and not a separate directive?

[theletterf]

I think we can roll with this one! I would just think of a warning in case a layout is missing what we consider mandatory directives (like hero).