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..7bba00285 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..b3f1d55e4 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} +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: + - id: apm +applies_to: + stack: ga + serverless: + observability: ga +``` +::: \ No newline at end of file