From 2319478b4d837f8731dea2948c0d516ea6ad02d9 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 5 Sep 2025 17:06:58 -0500 Subject: [PATCH 1/6] add more guidance on products --- docs/_snippets/products-list.md | 51 +++++++++++++++++++ docs/configure/content-set/navigation.md | 26 ++++++++-- docs/syntax/frontmatter.md | 65 +++++++++--------------- 3 files changed, 97 insertions(+), 45 deletions(-) create mode 100644 docs/_snippets/products-list.md diff --git a/docs/_snippets/products-list.md b/docs/_snippets/products-list.md new file mode 100644 index 000000000..2f74473c3 --- /dev/null +++ b/docs/_snippets/products-list.md @@ -0,0 +1,51 @@ +`products` is a list of objects, each object has an `id` field. + +```yaml +products: + - id: apm +``` + +Each product ID is mapped to a full product name. +You use the product ID in the source files, and docs-builder will use the full product name in +a `product_name` `meta` tag in the generated HTML and YAML metadata in generated Markdown files, +which are used to drive elastic.co search functionality. + +:::{dropdown} Valid products IDs + +| Product ID | Product name | +|---------------------------------------------|-----------------------------------------------| +| `apm` | APM | +| `apm-agent` | APM Agent | +| `auditbeat` | Auditbeat | +| `beats` | Beats | +| `cloud-control-ecctl` | Elastic Cloud Control ECCTL | +| `cloud-enterprise` | Elastic Cloud Enterprise | +| `cloud-hosted` | Elastic Cloud Hosted | +| `cloud-kubernetes` | Elastic Cloud Kubernetes | +| `cloud-serverless` | Elastic Cloud Serverless | +| `cloud-terraform` | Elastic Cloud Terraform | +| `ecs` | Elastic Common Schema (ECS) | +| `ecs-logging` | ECS Logging | +| `edot-cf` | EDOT Cloud Forwarder | +| `edot-sdk` | Elastic Distribution of OpenTelemetry SDK | +| `edot-collector` | Elastic Distribution of OpenTelemetry Collector | +| `elastic-agent` | Elastic Agent | +| `elastic-serverless-forwarder` | Elastic Serverless Forwarder | +| `elastic-stack` | Elastic Stack | +| `elasticsearch` | Elasticsearch | +| `elasticsearch-client` | Elasticsearch Client | +| `filebeat` | Filebeat | +| `fleet` | Fleet | +| `heartbeat` | Heartbeat | +| `integrations` | Integrations | +| `kibana` | Kibana | +| `logstash` | Logstash | +| `machine-learning` | Machine Learning | +| `metricbeat` | Metricbeat | +| `observability` | Elastic Observability | +| `packetbeat` | Packetbeat | +| `painless` | Painless | +| `search-ui` | Search UI | +| `security` | Elastic Security | +| `winlogbeat` | Winlogbeat | +::: diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md index 318a32804..c7754fd41 100644 --- a/docs/configure/content-set/navigation.md +++ b/docs/configure/content-set/navigation.md @@ -49,6 +49,11 @@ Optional key. Defaults to `false`. When enabled turns soft line endings in the m ### `external_hosts` +% Or remove this section altogether? +```{applies_to} +product: deprecated 0.11.0 +``` + All links to external hosts must be declared in this section of `docset.yml`. Example: @@ -89,6 +94,17 @@ exclude: - '_*.md' ``` +### `products` + +Products that are covered in all pages in the doc set. + +:::{include} /_snippets/products-list.md +::: + +`products` can also be defined in the [page level frontmatter](/syntax/frontmatter.md#products). +If you define `products` in a page's Markdown file and the `docset.yml` file also includes `products`, docs-builder will combine the two lists. +You can _not_ override doc set level `products` at the page level. + ### `toc` Defines the table of contents (navigation) for the content set. A minimal toc is: @@ -107,7 +123,7 @@ The TOC in principle follows the directory structure on disk. - folder: subsection ``` -If a folder does not explicitly define `children` all markdown files within that folder are included automatically +If a folder does not explicitly define `children` all markdown files within that folder are included automatically If a folder does define `children` all markdown files within that folder have to be included. `docs-builder` will error if it detects dangling documentation files. @@ -122,8 +138,8 @@ If a folder does define `children` all markdown files within that folder have to #### Virtual grouping -A `file` element may include children to create a virtual grouping that -does not match the directory structure. +A `file` element may include children to create a virtual grouping that +does not match the directory structure. ```yaml ... @@ -137,7 +153,7 @@ A `file` may only select siblings and more deeply nested files as its children. #### Hidden files -A hidden file can be declared in the TOC. +A hidden file can be declared in the TOC. ```yaml - hidden: developer-pages.md ``` @@ -176,6 +192,6 @@ See [Attributes](./attributes.md) to learn more. As a rule, each `docset.yml` file can only be included once in the assembler. This prevents us from accidentally duplicating pages in the docs. However, there are times when you want to split content sets and include them partially in different areas of the TOC. That's what `toc.yml` files are for. These files split one documentation set into multiple “sub-TOCs,” each mapped to a different navigation node. -A `toc.yml` file may only declare a nested [TOC](#toc), other options are ignored. +A `toc.yml` file may only declare a nested [TOC](#toc), other options are ignored. A `toc.yml` may not link to further nested `toc.yml` files. Doing so will result in an error diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index dd353aa7c..04672da3f 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -43,43 +43,28 @@ See [](./applies.md) ## Products The products frontmatter is a list of products that the page relates to. -This is used for the "Products" filter in the Search UI. - -The products frontmatter is a list of objects, each object has an `id` field. - -| Product ID | Product Name | -|---------------------------------------------|-----------------------------------------------| -| `apm` | APM | -| `apm-agent` | APM Agent | -| `auditbeat` | Auditbeat | -| `beats` | Beats | -| `cloud-control-ecctl` | Elastic Cloud Control ECCTL | -| `cloud-enterprise` | Elastic Cloud Enterprise | -| `cloud-hosted` | Elastic Cloud Hosted | -| `cloud-kubernetes` | Elastic Cloud Kubernetes | -| `cloud-serverless` | Elastic Cloud Serverless | -| `cloud-terraform` | Elastic Cloud Terraform | -| `ecs` | Elastic Common Schema (ECS) | -| `ecs-logging` | ECS Logging | -| `edot-cf` | EDOT Cloud Forwarder | -| `edot-sdk` | Elastic Distribution of OpenTelemetry SDK | -| `edot-collector` | Elastic Distribution of OpenTelemetry Collector | -| `elastic-agent` | Elastic Agent | -| `elastic-serverless-forwarder` | Elastic Serverless Forwarder | -| `elastic-stack` | Elastic Stack | -| `elasticsearch` | Elasticsearch | -| `elasticsearch-client` | Elasticsearch Client | -| `filebeat` | Filebeat | -| `fleet` | Fleet | -| `heartbeat` | Heartbeat | -| `integrations` | Integrations | -| `kibana` | Kibana | -| `logstash` | Logstash | -| `machine-learning` | Machine Learning | -| `metricbeat` | Metricbeat | -| `observability` | Elastic Observability | -| `packetbeat` | Packetbeat | -| `painless` | Painless | -| `search-ui` | Search UI | -| `security` | Elastic Security | -| `winlogbeat` | Winlogbeat | + +:::{include} /_snippets/products-list.md +::: + +`products` can also be defined in the [`docset.yml` file](/configure/content-set/navigation.md#products). +If you define `products` in a page's Markdown file and the `docset.yml` file also includes `products`, docs-builder will combine the two lists. +You can _not_ override doc set level `products` at the page level. + +:::{tip} +`products` is distinct from `applies_to`, which is used to indicate feature availability and applicability. + +% Is this true? +For example, while a page might contain content that is _applicable_ to Elastic Cloud Serverless projects, +it might not be _about_ Elastic Cloud Serverless. In that case, you would include the `serverless` key in `applies_to`, +but _not_ include the `cloud-serverless` ID in `products`: + +```yaml +products: + - id: apm +applies_to: + stack: ga + serverless: + observability: ga +``` +::: \ No newline at end of file From 8f210ab2c231d4015b87da4b699171b7aebe0329 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 9 Sep 2025 09:28:44 -0500 Subject: [PATCH 2/6] apply suggestions from code review Co-authored-by: Fabrizio Ferri-Benedetti --- docs/configure/content-set/navigation.md | 2 +- docs/syntax/frontmatter.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md index c7754fd41..7bba00285 100644 --- a/docs/configure/content-set/navigation.md +++ b/docs/configure/content-set/navigation.md @@ -123,7 +123,7 @@ The TOC in principle follows the directory structure on disk. - folder: subsection ``` -If a folder does not explicitly define `children` all markdown files within that folder are included automatically +If a folder does not explicitly define `children` all Markdown files within that folder are included automatically If a folder does define `children` all markdown files within that folder have to be included. `docs-builder` will error if it detects dangling documentation files. diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index 04672da3f..81217ad50 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -52,7 +52,7 @@ If you define `products` in a page's Markdown file and the `docset.yml` file als You can _not_ override doc set level `products` at the page level. :::{tip} -`products` is distinct from `applies_to`, which is used to indicate feature availability and applicability. +The purpose of the `products` field is different from `applies_to`: the former provides metadata to search engines, while the latter indicates feature availability and applicability. % Is this true? For example, while a page might contain content that is _applicable_ to Elastic Cloud Serverless projects, From 039d581466814d20c69ee570e1c6c2ab3031bce0 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 9 Sep 2025 12:45:30 -0500 Subject: [PATCH 3/6] update docs/syntax/frontmatter.md Co-authored-by: florent-leborgne --- docs/syntax/frontmatter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index 81217ad50..b3f1d55e4 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -52,7 +52,7 @@ If you define `products` in a page's Markdown file and the `docset.yml` file als You can _not_ override doc set level `products` at the page level. :::{tip} -The purpose of the `products` field is different from `applies_to`: the former provides metadata to search engines, while the latter indicates feature availability and applicability. +The purpose of the `products` field is different from `applies_to`: the former provides metadata to elastic.co search engines, while the latter indicates feature availability and applicability. % Is this true? For example, while a page might contain content that is _applicable_ to Elastic Cloud Serverless projects, From 251216656ba896e95798c7f7ba695caae213e2bb Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 30 Sep 2025 08:33:30 -0500 Subject: [PATCH 4/6] Update docs/syntax/frontmatter.md --- docs/syntax/frontmatter.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index b3f1d55e4..d5b518ccb 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -51,13 +51,6 @@ The products frontmatter is a list of products that the page relates to. If you define `products` in a page's Markdown file and the `docset.yml` file also includes `products`, docs-builder will combine the two lists. You can _not_ override doc set level `products` at the page level. -:::{tip} -The purpose of the `products` field is different from `applies_to`: the former provides metadata to elastic.co search engines, while the latter indicates feature availability and applicability. - -% Is this true? -For example, while a page might contain content that is _applicable_ to Elastic Cloud Serverless projects, -it might not be _about_ Elastic Cloud Serverless. In that case, you would include the `serverless` key in `applies_to`, -but _not_ include the `cloud-serverless` ID in `products`: ```yaml products: From 0b95e8f074f7db51f5a03b4695e8d5eb45b570fb Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 30 Sep 2025 08:33:37 -0500 Subject: [PATCH 5/6] Update docs/syntax/frontmatter.md --- docs/syntax/frontmatter.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index d5b518ccb..e86bad027 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -50,14 +50,3 @@ The products frontmatter is a list of products that the page relates to. `products` can also be defined in the [`docset.yml` file](/configure/content-set/navigation.md#products). If you define `products` in a page's Markdown file and the `docset.yml` file also includes `products`, docs-builder will combine the two lists. You can _not_ override doc set level `products` at the page level. - - -```yaml -products: - - id: apm -applies_to: - stack: ga - serverless: - observability: ga -``` -::: \ No newline at end of file From 6862bb14a195e85e666f448bd002f4e74b71b074 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 30 Sep 2025 08:35:02 -0500 Subject: [PATCH 6/6] Update dropdown header for product IDs mapping --- docs/_snippets/products-list.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_snippets/products-list.md b/docs/_snippets/products-list.md index 2f74473c3..23d0cbec7 100644 --- a/docs/_snippets/products-list.md +++ b/docs/_snippets/products-list.md @@ -10,7 +10,7 @@ You use the product ID in the source files, and docs-builder will use the full p a `product_name` `meta` tag in the generated HTML and YAML metadata in generated Markdown files, which are used to drive elastic.co search functionality. -:::{dropdown} Valid products IDs +:::{dropdown} Products ID to full product name mapping | Product ID | Product name | |---------------------------------------------|-----------------------------------------------|