Hub pages 2/4: {card-group}, {link-card}, and {explore}

docs/_docset.yml

@@ -1,3 +1,3 @@
 project: 'doc-builder'
 max_toc_depth: 2
 dev_docs: true
@@ -110,13 +110,15 @@
       - file: applies-switch.md
       - file: automated_settings.md
       - file: buttons.md
+      - file: card-group.md
       - file: changelog.md
       - file: code.md
       - file: comments.md
       - file: contributors.md
       - file: csv-include.md
       - file: dropdowns.md
       - file: definition-lists.md
+      - file: explore.md
       - file: file_inclusion.md
       - file: footnotes.md
       - file: frontmatter.md
@@ -126,6 +128,7 @@
       - file: images.md
       - file: videos.md
       - file: kbd.md
+      - file: link-card.md
       - file: math.md
       - file: diagrams.md
       - file: lists.md

docs/examples/products/docs-builder.md

@@ -9,4 +9,216 @@ description: docs-builder documentation. Build, validate, and publish Elastic do
 :description: The toolchain that builds Elastic's documentation. Author in Markdown, validate cross-repository links, preview locally, and publish one unified site.
 :primary-action: [Install docs-builder](/getting-started/installation.md)
 :secondary-action: [Elastic documentation](docs-content://get-started/index.md)
+:tertiary-action: [Explore docs-builder](#explore)
 :::
+
+::::{card-group}
+:title: Get hands-on
+:id: hands-on
+:intro: New to the toolchain? Follow a guided path from install to published page.
+
+:::{link-card}
+title: Write your first page
+link: /getting-started/writing-content.md
+description: Author a page, add links, and preview it locally.
+links:
+  - label: Writing content
+    url: /getting-started/writing-content.md
+  - label: Pages and links
+    url: /getting-started/pages-and-links.md
+:::
+
+:::{link-card}
+title: Serve and publish
+link: /getting-started/serve.md
+description: Run the local preview server, then publish the built site.
+links:
+  - label: Serve locally
+    url: /getting-started/serve.md
+  - label: Publish
+    url: /getting-started/publish.md
+:::
+
+:::{link-card}
+title: Syntax reference
+link: /syntax/index.md
+description: Every directive and role the toolchain understands.
+links:
+  - label: Browse the syntax guide
+    url: /syntax/index.md
+  - label: Hub pages
+    url: /syntax/hub-pages.md
+:::
+::::
+
+::::{card-group}
+:title: Documentation this toolchain builds
+:id: solutions
+:intro: The published Elastic documentation, linked with cross-repository links.
+:variant: solutions
+
+:::{link-card}
+icon: elasticsearch
+variant: es
+title: Elasticsearch
+description: Search and analytics documentation.
+links:
+  - label: Search solution
+    url: docs-content://solutions/search.md
+  - label: Manage data
+    url: docs-content://manage-data/index.md
+:::
+
+:::{link-card}
+icon: observability
+variant: obs
+title: Observability
+description: Logs, metrics, traces, and alerting documentation.
+links:
+  - label: Observability solution
+    url: docs-content://solutions/observability.md
+  - label: Explore and analyze
+    url: docs-content://explore-analyze/index.md
+:::
+
+:::{link-card}
+icon: security
+variant: sec
+title: Security
+description: SIEM, endpoint, and detection documentation.
+links:
+  - label: Security solution
+    url: docs-content://solutions/security.md
+  - label: Deploy and manage
+    url: docs-content://deploy-manage/index.md
+:::
+::::
+
+:::::{explore}
+:id: explore
+:title: Explore docs-builder
+:intro: Find what you need, organized by task, from authoring and building to publishing and operating.
+
+::::{card-group}
+:title: Authoring
+:id: authoring
+
+:::{link-card}
+title: Syntax
+links:
+  - label: Directives
+    url: /syntax/directives.md
+  - label: Hub pages
+    url: /syntax/hub-pages.md
+  - label: Hero
+    url: /syntax/hero.md
+:::
+
+:::{link-card}
+title: Card directives
+links:
+  - label: Card group
+    url: /syntax/card-group.md
+  - label: Link card
+    url: /syntax/link-card.md
+  - label: Explore
+    url: /syntax/explore.md
+  - label: Page card
+    url: /syntax/page-card.md
+:::
+
+:::{link-card}
+title: Getting started
+links:
+  - label: Installation
+    url: /getting-started/installation.md
+  - label: Writing content
+    url: /getting-started/writing-content.md
+  - label: Pages and links
+    url: /getting-started/pages-and-links.md
+:::
+
+:::{link-card}
+title: Formatting
+links:
+  - label: Code blocks
+    url: /syntax/code.md
+  - label: Tables
+    url: /syntax/tables.md
+  - label: Lists
+    url: /syntax/lists.md
+  - label: Admonitions
+    url: /syntax/admonitions.md
+:::
+
+:::{link-card}
+title: Page metadata
+links:
+  - label: Frontmatter
+    url: /syntax/frontmatter.md
+  - label: Links
+    url: /syntax/links.md
+  - label: Substitutions
+    url: /syntax/substitutions.md
+:::
+::::
+
+::::{card-group}
+:title: Builds and configuration
+:id: builds
+
+:::{link-card}
+title: Build types
+links:
+  - label: Isolated builds
+    url: /documentation/isolated/configure/index.md
+  - label: Assembler
+    url: /documentation/assembler/configure/index.md
+  - label: Codex
+    url: /documentation/codex/index.md
+:::
+
+:::{link-card}
+title: Catalog
+links:
+  - label: Products
+    url: /documentation/catalog/products.md
+  - label: Versions
+    url: /documentation/catalog/versions.md
+:::
+
+:::{link-card}
+title: Catalog reference
+links:
+  - label: Synonyms
+    url: /documentation/catalog/synonyms.md
+  - label: Legacy URLs
+    url: /documentation/catalog/legacy-url-mappings.md
+:::
+::::
+
+::::{card-group}
+:title: Structured data and operations
+:id: data
+
+:::{link-card}
+title: Exporters
+links:
+  - label: Overview
+    url: /data/exporters/index.md
+  - label: LLM markdown
+    url: /data/exporters/llm.md
+  - label: Plain text
+    url: /data/exporters/plain-text.md
+:::
+
+:::{link-card}
+title: Operations
+links:
+  - label: Distributed builds
+    url: /documentation/distributed-builds.md
+  - label: Infrastructure
+    url: /documentation/assembler/infrastructure.md
+:::
+::::
+:::::

docs/syntax/card-group.md

@@ -0,0 +1,49 @@
+# Card group
+
+A section heading and a card grid container. It wraps one or more [`{link-card}`](link-card.md) directives.
+
+See the [docs-builder documentation hub](../examples/products/docs-builder.md) for both rendering modes on one page.
+
+## Basic
+
+```markdown
+::::{card-group}
+:title: Install and administer
+:id: install
+
+:::{link-card}
+title: Self-managed
+link: /getting-started/installation.md
+description: Run on your own infrastructure.
+:::
+
+:::{link-card}
+title: Serve locally
+link: /getting-started/serve.md
+description: Preview the site while you write.
+:::
+::::
+```
+
+The outer fence uses **four** colons, so the inner three-colon fences are not read as a closing fence. Add as many extra colons to the outer fence as the nesting needs.
+
+## Options
+
+| Option | Notes |
+|---|---|
+| `:title:` | H2 heading. Optional. Without it, only the grid renders. |
+| `:intro:` | Intro paragraph below the heading. |
+| `:id:` | Section anchor. |
+| `:variant:` | Set to `solutions` to lock a 3-up grid. |
+
+## Layout
+
+By default the grid auto-fills 1, 2, or 3 columns based on the available width. Card heights match within a row.
+
+With `:variant: solutions`, the grid locks to three equal columns, stepping to two and then one at narrower widths. A fourth card wraps to the next row instead of compressing the layout into a narrow fourth column.
+
+## Inside `{explore}`
+
+Nest a card group in an [`{explore}`](explore.md) section and it renders as a collapsible accordion instead of a titled grid. The `:title:` becomes the accordion header, and each child [`{link-card}`](link-card.md) renders as a link column.
+
+No option controls this. The `{explore}` ancestor drives it. That keeps every card grid elsewhere on the site working unchanged, and it means an author wraps existing groups in `{explore}` rather than learning a second directive.

docs/syntax/explore.md

@@ -0,0 +1,72 @@
+# Explore
+
+The browse-everything section of a [hub page](hub-pages.md). It is a titled band holding a stack of collapsible accordions, and it wraps one or more [`{card-group}`](card-group.md) directives.
+
+A hub's full link list can run to nine or ten sections. Without grouping that is a very long page, so `{explore}` collapses it into a scannable stack.
+
+See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered stack.
+
+## Basic
+
+```markdown
+:::::{explore}
+:id: explore
+:title: Explore the docs toolchain
+:intro: Find what you need, organized by task.
+
+::::{card-group}
+:title: Quick links
+:id: quick-links
+
+:::{link-card}
+title: Releases and APIs
+links:
+  - label: Exporters
+    url: /data/exporters/index.md
+  - label: API reference
+    url: /data/api.md
+:::
+::::
+
+::::{card-group}
+:title: Authoring
+:id: authoring
+
+:::{link-card}
+title: Syntax
+links:
+  - label: Directives
+    url: /syntax/directives.md
+:::
+::::
+:::::
+```
+
+## Options
+
+| Option | Notes |
+|---|---|
+| `:title:` | **Required.** H2 heading, for example "Explore Elasticsearch". |
+| `:intro:` | Intro paragraph below the heading. |
+| `:id:` | Section anchor. Use `explore` so `{hero}`'s tertiary action can jump to it. |
+
+## What nesting changes
+
+`{explore}` carries no options for the accordions. Nesting drives everything:
+
+- Each [`{card-group}`](card-group.md) inside becomes one accordion. Its `:title:` is the accordion header.
+- The first accordion is expanded. The rest are collapsed.
+- A reader can expand as many accordions as they want. Expanding one does not collapse the others.
+- Each [`{link-card}`](link-card.md) inside renders as a link column rather than a bordered card.
+
+Toggling uses native `<details>` and `<summary>`, so it works without JavaScript.
+
+## Fence depth
+
+Nesting three directives needs three fence widths. The outer fence always needs one more colon than its deepest child:
+
+| Directive | Fence |
+|---|---|
+| `{explore}` | `:::::` |
+| `{card-group}` | `::::` |
+| `{link-card}` | `:::` |

docs/syntax/hero.md

@@ -4,7 +4,7 @@ A full-bleed identity band with a product icon, page title, description, and up
 
 All hero content comes from options. The directive body is not used.
 
-See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a rendered hero.
+See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered hero.
 
 ## Basic
 

docs/syntax/hub-pages.md

@@ -4,7 +4,7 @@ A hub page is a product-scoped landing page. It gives a reader one 360° view of
 
 Hub pages are composed entirely from directives. There is no free-form body content. That constraint is deliberate. It lets every link validate at build time, and it keeps every hub structurally consistent whoever authors it.
 
-See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a complete page.
+See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a complete page.
 
 ## Enable the layout
 
@@ -54,6 +54,9 @@ Write both deliberately. The search body indexes the hero title and description
 | Directive | Purpose |
 |---|---|
 | [`{hero}`](hero.md) | Identity band. Carries the product icon, the page title, a description, and up to three actions. |
+| [`{card-group}`](card-group.md) | Section heading and card grid. Renders as an accordion inside `{explore}`. |
+| [`{link-card}`](link-card.md) | One card: title, description, and a list of links. Renders as a link column inside `{explore}`. |
+| [`{explore}`](explore.md) | The browse-everything section. A stack of collapsible accordions. |
 
 ## Page skeleton