diff --git a/config/assembler.yml b/config/assembler.yml index d1187bdfa4..53f07fe842 100644 --- a/config/assembler.yml +++ b/config/assembler.yml @@ -77,6 +77,7 @@ shared_configuration: ### narrative: checkout_strategy: full + current: hub-pages ### # 'references' defines a map of `elastic/ * diff --git a/config/navigation-v2.yml b/config/navigation-v2.yml index c0550c370d..37eec23229 100644 --- a/config/navigation-v2.yml +++ b/config/navigation-v2.yml @@ -4266,6 +4266,17 @@ nav: - page: docs-content://solutions/security/apis.md title: APIs + - section: Products + url: /products/ + dropdown: true + children: + - label: Stack products + children: + - page: docs-content://products/elasticsearch/v9.md + title: Elasticsearch + - page: docs-content://products/kibana/v9.md + title: Kibana + - section: APIs url: https://www.elastic.co/docs/api diff --git a/config/navigation.yml b/config/navigation.yml index e39a84043d..ccf2e0465a 100644 --- a/config/navigation.yml +++ b/config/navigation.yml @@ -17,6 +17,7 @@ toc: ############# # NARRATIVE # ############# + - toc: products - toc: get-started - toc: solutions - toc: manage-data diff --git a/config/products.yml b/config/products.yml index 31a7fe4bc4..6bc7822a3f 100644 --- a/config/products.yml +++ b/config/products.yml @@ -151,6 +151,7 @@ products: elasticsearch: display: 'Elasticsearch' versioning: 'stack' + hub: 'products/elasticsearch/v9' elasticsearch-client: display: 'Elasticsearch Client' versioning: 'stack' @@ -211,6 +212,7 @@ products: kibana: display: 'Kibana' versioning: 'stack' + hub: 'products/kibana/v9' logstash: display: 'Logstash' versioning: 'stack' diff --git a/config/whats-new.yml b/config/whats-new.yml new file mode 100644 index 0000000000..f3ea2be702 --- /dev/null +++ b/config/whats-new.yml @@ -0,0 +1,86 @@ +### +# Centralized "What's new" feed used by the {whats-new} directive. +# +# Any page can render a product's recent highlights with: +# +# :::{whats-new} +# :product: kibana +# ::: +# +# The {whats-new} directive looks the product up in this file and renders the +# full panel (header + items). Authors only edit this file, and the directive +# stays trivial in markdown. +# +# An optional `id` and `badge` per product control the section anchor and the +# small badge shown to the left of the title. The default badge is "New". +### + +products: + + kibana: + title: What's new in Kibana + id: whats-new + release-links: + - label: Stack 9.4.1 + url: https://www.elastic.co/docs/release-notes/kibana + - label: Serverless · Apr 1, 2026 + url: https://www.elastic.co/docs/release-notes/cloud-serverless + upgrade-link: + label: Upgrade guide + url: https://www.elastic.co/docs/deploy-manage/upgrade/deployment-or-cluster + items: + - title: Dashboards and visualizations APIs + description: Programmatically create and manage dashboards and visualizations, so you can automate reporting and version-control your analytics. + link: https://www.elastic.co/docs/api/doc/kibana + date: 9.4 preview + tag: Dashboards + featured: true + - title: AI agent skills + description: Teach AI coding agents to work with the Elastic stack. + link: https://www.elastic.co/docs/explore-analyze/ai-features/agent-skills + date: Mar 2026 + tag: AI Assistant + - title: Agent Builder + description: Build custom AI agents that reason over your data. + link: https://www.elastic.co/docs/explore-analyze/ai-features/elastic-agent-builder + date: 9.3 GA + tag: AI Assistant + - title: Workflows + description: Automate tasks with Kibana actions, HTTP calls, and AI agents. + link: https://www.elastic.co/docs/explore-analyze/workflows + date: 9.3 preview + tag: Automation + + elasticsearch: + title: What's new in Elasticsearch + id: whats-new + release-links: + - label: Stack 9.4.1 + url: https://www.elastic.co/docs/release-notes/elasticsearch + - label: Serverless · Apr 1, 2026 + url: https://www.elastic.co/docs/release-notes/cloud-serverless + upgrade-link: + label: Upgrade guide + url: https://www.elastic.co/docs/deploy-manage/upgrade/deployment-or-cluster + items: + - title: semantic_text field type + description: Simplify semantic search. No pipeline setup needed, just define the field and start querying. + link: https://www.elastic.co/docs/solutions/search/semantic-search/semantic-search-semantic-text + date: 9.4 GA + tag: Search + featured: true + - title: ES|QL improvements + description: New functions, cross-cluster support, and dense vector operations directly in ES|QL queries. + link: https://www.elastic.co/docs/reference/query-languages/esql/esql-getting-started + date: '9.4' + tag: Query languages + - title: Inference API expansion + description: Connect to external AI models for embeddings and reranking. + link: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put + date: '9.4' + tag: AI + - title: Breaking changes in 9.x + description: Review removed settings, deprecated APIs, and behavioral changes before upgrading from 8.x. + link: https://www.elastic.co/docs/release-notes/elasticsearch/breaking-changes + date: Upgrade guide + tag: Upgrade diff --git a/docs/_docset.yml b/docs/_docset.yml index 51476fabf3..ad75ac25a7 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -144,6 +144,7 @@ toc: - file: applies-switch.md - file: automated_settings.md - file: buttons.md + - file: card-group.md - file: changelog.md - file: code.md - file: comments.md @@ -153,13 +154,18 @@ toc: - file: dropdowns.md - file: definition-lists.md - file: example_blocks.md + - file: explore.md - file: file_inclusion.md - file: footnotes.md - file: frontmatter.md + - file: hero.md + - file: hub-pages.md - file: icons.md + - file: get-started.md - file: images.md - file: videos.md - file: kbd.md + - file: link-card.md - file: math.md - file: diagrams.md - file: lists.md @@ -168,6 +174,7 @@ toc: - file: storybook.md - file: links.md - file: list-sub-pages.md + - file: on-this-page.md - file: page-card.md - file: passthrough.md - file: sidebars.md @@ -179,6 +186,7 @@ toc: - file: tabs.md - file: tagged_regions.md - file: titles.md + - file: whats-new.md - cli: cli-schema.json folder: cli children: @@ -213,6 +221,14 @@ toc: - folder: testing children: - file: index.md + - folder: products + children: + - folder: elasticsearch + children: + - file: v9.md + - folder: kibana + children: + - file: v9.md - file: kibana-settings-yaml-samples.md - file: security-settings.md - file: req.md diff --git a/docs/syntax/card-group.md b/docs/syntax/card-group.md new file mode 100644 index 0000000000..d627531060 --- /dev/null +++ b/docs/syntax/card-group.md @@ -0,0 +1,47 @@ +# Card group + +A section heading + a card grid container. Wraps one or more [`{link-card}`](link-card.md) directives. + +## Basic + +```markdown +::::{card-group} +:title: Install and administer +:id: install + +:::{link-card} +title: Self-managed +link: /deploy/self-managed +description: Run on your own infrastructure. +links: + - { label: Docker, url: /deploy/docker } +::: + +:::{link-card} +title: Elastic Cloud Hosted +link: /deploy/cloud +description: Managed deployments on AWS, GCP, or Azure. +::: +:::: +``` + +The outer fence uses **four** colons (`::::`) so the inner three-colon `:::` fences for the cards aren't interpreted as a closing fence. Use as many extra colons on the outer fence as you need to nest cleanly. + +## Options + +| Option | Notes | +|---|---| +| `:title:` | H2 heading. Optional — without it, only the grid renders. | +| `:intro:` | Optional intro paragraph below the heading. | +| `:id:` | Section anchor. Picked up by [`{on-this-page}`](on-this-page.md). | +| `:variant:` | Optional layout variant. Set to `solutions` to lock a 3-up grid that steps down to 2 then 1 column and tolerates a fourth card without shrinking into a narrow fourth column. | + +## Layout + +By default the grid auto-fills 1, 2, or 3 columns based on viewport width using `grid-template-columns: repeat(auto-fill, minmax(310px, 1fr))`. Card heights match within a row. + +With `:variant: solutions`, the grid is locked to three equal columns (two below 980px, one below 640px). A fourth card wraps to the next row rather than compressing the layout. + +## Inside `{explore}` + +When a card-group sits inside an [`{explore}`](explore.md) section, it renders as a collapsible **accordion group** instead of a titled grid: the `:title:` becomes the accordion header and the child [`{link-card}`](link-card.md)s render as link columns. No extra options are needed — the `{explore}` ancestor drives the change. diff --git a/docs/syntax/explore.md b/docs/syntax/explore.md new file mode 100644 index 0000000000..b409ad8772 --- /dev/null +++ b/docs/syntax/explore.md @@ -0,0 +1,74 @@ +# Explore + +The **Explore {product}** section of a [hub page](hub-pages.md): a titled band that +houses a stack of collapsible **accordion groups**. It wraps one or more +[`{card-group}`](card-group.md) directives. Inside `{explore}`, each card-group +renders as an accordion and each [`{link-card}`](link-card.md) renders as a titled +link **column** instead of a bordered card. + +The first accordion in the stack is expanded by default, and the rest are collapsed. +Toggling uses native `
`/``, so it works without JavaScript. + +## Basic + +```markdown +:::::{explore} +:title: Explore Kibana +:intro: Explore the apps and capabilities that help you act on your data. + +::::{card-group} +:title: Install & admin +:id: install + +:::{link-card} +title: Self-managed +link: /deploy-manage/deploy/self-managed +links: + - { label: Docker, url: /deploy/docker } + - { label: Configure, url: /deploy/configure } +aside: + label: Even more + links: + - { label: RPM, url: /deploy/rpm } + - { label: Windows, url: /deploy/windows } +::: +:::: + +::::{card-group} +:title: Visualize & analyze +:id: visualize + +:::{link-card} +title: Dashboards +link: /explore-analyze/dashboards +links: + - { label: Create a dashboard, url: /dashboards/create } +::: +:::: +::::: +``` + +The outer `{explore}` fence uses **five** colons so the four-colon `::::` card-group +fences and three-colon `:::` link-card fences nest without closing it early. Add more +colons on the outer fence if you need to nest deeper. + +## Options + +| Option | Notes | +|---|---| +| `:title:` | H2 heading for the section (for example, `Explore Kibana`). Required. | +| `:intro:` | Optional intro paragraph below the heading. | +| `:id:` | Section anchor. | + +## How nested directives change + +Inside `{explore}`, the same authoring you already use for card grids is reinterpreted: + +| Directive | Standalone rendering | Inside `{explore}` | +|---|---|---| +| `{card-group}` | Section heading + card grid | A collapsible accordion group (title in the header, cards inside) | +| `{link-card}` | A bordered card | A titled link **column** (title and link list, with the `description` not shown in column mode) | +| `{link-card}` `aside` | Inline "label: A · B · C" line | An **"Even more"** badge cluster under the column | + +Because the effect is driven by the `{explore}` ancestor, the card-group and link-card +bodies don't need any extra options. Wrapping them is enough. diff --git a/docs/syntax/get-started.md b/docs/syntax/get-started.md new file mode 100644 index 0000000000..ffa7bfce9d --- /dev/null +++ b/docs/syntax/get-started.md @@ -0,0 +1,67 @@ +# Get started section + +The first section of a hub-page body: a short onboarding funnel with an intro line and a set of numbered steps. A step can present two equally-weighted start **options** (for example, run locally versus try on Cloud), be a plain informational step, or link out as a whole card. + +## Basic + +```markdown +:::{get-started} +title: Get started in 3 steps +intro: Spin up Elasticsearch and Kibana, connect your data, and start exploring in minutes. +steps: + - title: Run Elasticsearch and Kibana + options: + - label: Run locally + description: Spin up Elasticsearch and Kibana on your machine for development. + code: curl -fsSL https://elastic.co/start-local | sh + language: sh + url: /deploy-manage/deploy/self-managed/install-kibana + url-label: Install self-managed + - label: Try on Cloud + description: Start a free Elastic Cloud trial. No local setup needed. + url: https://cloud.elastic.co/registration + url-label: Start a free trial + - title: Connect your data + description: Point Kibana at your data and create a data view. + link: /manage-data/ingest + link-label: Ingest data + - title: Explore and visualize + description: Open Discover, then build your first chart and dashboard. + link: /explore-analyze/kibana-data-exploration-learning-tutorial + link-label: Start the tutorial +::: +``` + +## Fields + +| Field | Required | Description | +|---|---|---| +| `title` | yes | Section heading, for example `Get started in 3 steps`. | +| `intro` | no | One-line lead sentence. Rendered as inline markdown. | +| `steps[].title` | yes | Step heading, shown next to the step number. | +| `steps[].description` | no | Short supporting sentence. Rendered as inline markdown. | +| `steps[].link` | no | When set, the whole step is a clickable card linking here. | +| `steps[].link-label` | no | Call-to-action label for a link step. Defaults to `Open`. | +| `steps[].options[]` | no | Two or more equally-weighted start options, rendered side by side. | +| `steps[].options[].label` | no | Option heading, for example `Run locally`. | +| `steps[].options[].description` | no | Short supporting sentence. Rendered as inline markdown. | +| `steps[].options[].code` | no | A command shown in a copyable snippet (the "run locally" path). | +| `steps[].options[].language` | no | Syntax-highlighting language for the snippet (for example `sh`). | +| `steps[].options[].url` | no | Destination for the option. Rendered as a text link when the option also has `code`, or as a button otherwise. | +| `steps[].options[].url-label` | no | Label for the option link/button. | + +An earlier top-level `install` / `tutorial` pair is still accepted for backward compatibility, but new pages should express the two start paths as `options` on the first step instead. + +## Linking the hero to this section + +The rendered section carries `id="get-started"`, so a [`{hero}`](hero.md) action can scroll to it instead of adding a competing entry point: + +```markdown +:primary-action: [Get started](#get-started) +``` + +## When to use + +`{get-started}` is the standard "front door" section between the [`{hero}`](hero.md) and the rest of the hub body. It's optional. Skip it when the hero already says what readers need to know next. + +It is **not** an admonition. For caution / note / tip-style callouts inside body content, use the existing [admonitions](admonitions.md). diff --git a/docs/syntax/hero.md b/docs/syntax/hero.md new file mode 100644 index 0000000000..68d9c19f6a --- /dev/null +++ b/docs/syntax/hero.md @@ -0,0 +1,50 @@ +# Hero + +A full-bleed hero band with a product icon, page title, description, and up to three call-to-action buttons. Designed for the [hub layout](hub-pages.md) but reusable on any page. + +All hero content is supplied via options. The directive body is not used. + +## Basic + +```markdown +:::{hero} +:icon: kibana +:title: Kibana documentation hub +:description: The UI for the Elasticsearch platform. +:primary-action: [Get started](#get-started) +:secondary-action: [What's new](#whats-new) +:tertiary-action: [Explore Kibana docs](#explore) +::: +``` + +The `:title:` option doubles as the page title (no body H1 needed). `:description:` supports inline markdown, including links, bold, and emphasis. + +On the hub pages the three actions are in-page jumps to the main sections: **Get started** (`#get-started`), **What's new** (`#whats-new`), and **Explore {product} docs** (`#explore`). An action whose URL starts with `#` renders with a downward chevron to signal an in-page jump. Actions are optional, so omit them for a pure identity hero. + +## Options + +| Option | Type | Notes | +|---|---|---| +| `:title:` | string | **Required.** Page heading shown next to the icon. Also picked up as the document's page title. | +| `:description:` | inline markdown | One-line summary shown below the title. Supports bold, italics, and links. | +| `:icon:` | string | Product key. Resolves to an inline SVG via the product-icon lookup. Known keys: `elasticsearch`, `kibana`, `observability`, `security`. Unknown keys fall back to a single-letter chip. | +| `:primary-action:` | markdown link | First call-to-action button, given slightly more emphasis. Format: `[Label](/url)` or `[Label](#anchor)`. | +| `:secondary-action:` | markdown link | Second call-to-action button (outline). Format: `[Label](/url)` or `[Label](#anchor)`. | +| `:tertiary-action:` | markdown link | Third call-to-action button (outline). Format: `[Label](/url)` or `[Label](#anchor)`. | + +Release cadence (latest version, serverless deployment date, release-notes links) lives in the [`{whats-new}`](whats-new.md) section, not the hero. + +## Actions + +```markdown +:::{hero} +:icon: elasticsearch +:title: Elasticsearch documentation hub +:description: The distributed search and analytics engine. +:primary-action: [Get started](#get-started) +:secondary-action: [What's new](#whats-new) +:tertiary-action: [Explore Elasticsearch docs](#explore) +::: +``` + +Each action is a single markdown link. Actions render left to right in the order primary, secondary, tertiary. Anchor links (`#section`) get a downward chevron; other links render as plain buttons. diff --git a/docs/syntax/hub-pages.md b/docs/syntax/hub-pages.md new file mode 100644 index 0000000000..5ec3a3e66c --- /dev/null +++ b/docs/syntax/hub-pages.md @@ -0,0 +1,115 @@ +--- +products: + - id: elasticsearch + - id: kibana +--- + +# Hub pages + +Hub pages are product-scoped landing pages — a 360° overview of one product across versions, deployment types, and surfaces. They're enabled by setting `layout: hub` in the page's frontmatter and composed from a small set of dedicated directives. + +## Enable the layout + +```yaml +--- +layout: hub +--- +``` + +The `hub` layout drops the right-rail "On this page" TOC and the prev/next nav. The body owns the full width of the content column so directives can render full-bleed sections. + +## Directives + +| Directive | Purpose | +|-----------|---------| +| [`{hero}`](hero.md) | Full-bleed page hero with product icon, title, search, version dropdown, and quick-action pills. | +| [`{on-this-page}`](on-this-page.md) | Auto-generated inline TOC linking each section anchor on the page. | +| [`{get-started}`](get-started.md) | Onboarding funnel: intro line, install snippet, tutorial link, and numbered steps. | +| [`{whats-new}`](whats-new.md) | "What's new" panel populated from `config/whats-new.yml`. | +| [`{card-group}`](card-group.md) | Section heading + card grid container. Renders as an accordion group inside `{explore}`. | +| [`{link-card}`](link-card.md) | Rich card with title, description, primary link list, and optional aside. Renders as a link column inside `{explore}`. | +| [`{explore}`](explore.md) | "Explore {product}" section: a stack of collapsible accordion groups wrapping several `{card-group}`s. | + +## Page skeleton + +```markdown +--- +layout: hub +--- + +:::{hero} +:icon: kibana +:title: Kibana +:description: The UI for the Elasticsearch platform. +:releases: Latest: [Stack 9.4.1](/rn) (Mar 28, 2026) +::: + +:::{on-this-page} +::: + +:::{get-started} +title: Get started in 3 steps +intro: Spin up Kibana, connect your data, and start exploring in minutes. +tutorial: + label: Tutorial + url: /tutorial +steps: + - icon: launch + title: Run Kibana + description: Start locally, run in Docker, or open a free Cloud trial. +::: + +:::{whats-new} +:product: kibana +::: + +::::{card-group} +:title: Install and administer +:id: install + +:::{link-card} +title: Self-managed +link: /deploy-manage/deploy/self-managed +description: Run Kibana on your own infrastructure. +links: + - { label: Docker, url: /deploy/docker } + - { label: Configure, url: /deploy/configure } +::: +:::: +``` + +Group the remaining card-groups under an [`{explore}`](explore.md) section so they render +as a stack of collapsible accordions: + +```markdown +:::::{explore} +:title: Explore Kibana +:intro: Explore the apps and capabilities that help you act on your data. + +::::{card-group} +:title: Install and administer +:id: install + +:::{link-card} +title: Self-managed +link: /deploy-manage/deploy/self-managed +links: + - { label: Docker, url: /deploy/docker } +::: +:::: +::::: +``` + +## Product badges + +Every regular (non-hub) page that declares one or more `products:` in its frontmatter automatically gets a clickable badge above its H1, linking to that product's hub page. The badge → hub URL mapping is set per product in [`config/products.yml`](../configure/site/products.md): + +```yaml +products: + kibana: + display: 'Kibana' + versioning: 'stack' + hub: 'products/kibana/9.0' # path slug -- relative to site root +``` + +When `hub:` is null, no badge renders for that product. diff --git a/docs/syntax/link-card.md b/docs/syntax/link-card.md new file mode 100644 index 0000000000..5b815522bf --- /dev/null +++ b/docs/syntax/link-card.md @@ -0,0 +1,74 @@ +# Link card + +A rich card with a title, description, primary link list, and an optional aside. Designed to live inside a [`{card-group}`](card-group.md), but renders standalone too. + +## Basic + +```markdown +:::{link-card} +title: Discover +link: /discover +description: Browse documents, filter, and query your indices in real time. +links: + - label: Get started with Discover + url: /discover/get-started + - label: Use ES|QL in Kibana + url: /esql +::: +``` + +The card body is **YAML, not markdown** — the directive expects a fixed schema and renders it. Authors don't write HTML, fences, or any directive options; they fill in fields. + +## Schema + +```yaml +title: Discover # required -- card heading +link: /discover/ # optional -- makes the title clickable +description: One-paragraph blurb. # optional +icon: elasticsearch # optional -- product-keyed inline SVG +variant: es # optional accent: es | obs | sec +links: # optional -- primary link list + - label: Get started + url: /discover/get-started + - label: Use ES|QL + url: /esql +aside: # optional bottom rail + label: Panel types + links: + - { label: Visualizations, url: /viz } + - { label: Maps, url: /maps } + - { label: Text, url: /text } +``` + +## Variants + +`variant: es | obs | sec` adds a left-border accent in the corresponding solution color (yellow / pink / teal). Use for solution cards. + +```markdown +:::{link-card} +title: Elasticsearch +link: /solutions/elasticsearch +icon: elasticsearch +variant: es +description: Build powerful search and RAG applications. +links: + - { label: Solution overview, url: /solutions/elasticsearch } + - { label: Get started, url: /solutions/elasticsearch/get-started } +aside: + label: Key features + links: + - { label: Vector search, url: /solutions/search/vector } + - { label: Semantic search, url: /solutions/search/semantic } +::: +``` + +## Aside + +The optional `aside` adds a separator line and a small label + dot-separated inline link list. Use it for supplementary references that don't fit the primary link list (e.g. "Panel types", "Chart types", "Key features"). + +## Errors + +The directive emits build errors when: + +- The body isn't valid YAML. +- `title` is missing or empty. diff --git a/docs/syntax/on-this-page.md b/docs/syntax/on-this-page.md new file mode 100644 index 0000000000..1674608297 --- /dev/null +++ b/docs/syntax/on-this-page.md @@ -0,0 +1,25 @@ +# On this page + +Inline TOC chip. Auto-collects every [`{card-group}`](card-group.md) and [`{whats-new}`](whats-new.md) on the same page that has both an `id` and a `title`, and renders them as middle-dot-separated anchor links inside a single rounded panel. + +## Basic + +```markdown +:::{on-this-page} +::: +``` + +That's the whole directive — no options, no body. Drop it once on a hub page (typically right after the [`{hero}`](hero.md)) and it stays in sync as you add or remove sections. + +## How items are collected + +For each section directive on the page, an item is added to the chip when: + +- The directive declares an `id` (becomes the anchor — `#install`). +- The directive declares a `title` (becomes the link label). + +`{card-group}`s with no `:title:` are skipped. `{whats-new}` panels populated from `config/whats-new.yml` get their `id` and `title` from that file; if the entry sets neither, the `{whats-new}` block is skipped. + +## Order + +Items appear in document order — top to bottom of the page. diff --git a/docs/syntax/whats-new.md b/docs/syntax/whats-new.md new file mode 100644 index 0000000000..50a3032409 --- /dev/null +++ b/docs/syntax/whats-new.md @@ -0,0 +1,66 @@ +# What's new + +A section with a heading, subtitle, and a "View release notes" link on the right, followed by a grid of highlight cards. Each card has an optional badge, a date and category tag, a title, a description, and a "Read more" link. One card can be marked `featured` to span two columns. + +## Centralized lookup (recommended) + +Edit content in one place — [`config/whats-new.yml`](../configure/site/products.md) — and any page can render a product's panel with a one-line directive: + +```markdown +:::{whats-new} +:product: kibana +::: +``` + +`config/whats-new.yml` schema: + +```yaml +products: + kibana: + title: What's new in Kibana + id: whats-new # used as the section anchor + release-links: # rendered as "Latest release notes: