Skip to content

Commit 2319478

Browse files
colleenmcginniscolleenmcginnis
committed
add more guidance on products
1 parent 72e6dfe commit 2319478

File tree

3 files changed

+97
-45
lines changed

3 files changed

+97
-45
lines changed

‎docs/_snippets/products-list.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
`products` is a list of objects, each object has an `id` field.
2+
3+
```yaml
4+
products:
5+
- id: apm
6+
```
7+
8+
Each product ID is mapped to a full product name.
9+
You use the product ID in the source files, and docs-builder will use the full product name in
10+
a `product_name` `meta` tag in the generated HTML and YAML metadata in generated Markdown files,
11+
which are used to drive elastic.co search functionality.
12+
13+
:::{dropdown} Valid products IDs
14+
15+
| Product ID | Product name |
16+
|---------------------------------------------|-----------------------------------------------|
17+
| `apm` | APM |
18+
| `apm-agent` | APM Agent |
19+
| `auditbeat` | Auditbeat |
20+
| `beats` | Beats |
21+
| `cloud-control-ecctl` | Elastic Cloud Control ECCTL |
22+
| `cloud-enterprise` | Elastic Cloud Enterprise |
23+
| `cloud-hosted` | Elastic Cloud Hosted |
24+
| `cloud-kubernetes` | Elastic Cloud Kubernetes |
25+
| `cloud-serverless` | Elastic Cloud Serverless |
26+
| `cloud-terraform` | Elastic Cloud Terraform |
27+
| `ecs` | Elastic Common Schema (ECS) |
28+
| `ecs-logging` | ECS Logging |
29+
| `edot-cf` | EDOT Cloud Forwarder |
30+
| `edot-sdk` | Elastic Distribution of OpenTelemetry SDK |
31+
| `edot-collector` | Elastic Distribution of OpenTelemetry Collector |
32+
| `elastic-agent` | Elastic Agent |
33+
| `elastic-serverless-forwarder` | Elastic Serverless Forwarder |
34+
| `elastic-stack` | Elastic Stack |
35+
| `elasticsearch` | Elasticsearch |
36+
| `elasticsearch-client` | Elasticsearch Client |
37+
| `filebeat` | Filebeat |
38+
| `fleet` | Fleet |
39+
| `heartbeat` | Heartbeat |
40+
| `integrations` | Integrations |
41+
| `kibana` | Kibana |
42+
| `logstash` | Logstash |
43+
| `machine-learning` | Machine Learning |
44+
| `metricbeat` | Metricbeat |
45+
| `observability` | Elastic Observability |
46+
| `packetbeat` | Packetbeat |
47+
| `painless` | Painless |
48+
| `search-ui` | Search UI |
49+
| `security` | Elastic Security |
50+
| `winlogbeat` | Winlogbeat |
51+
:::

‎docs/configure/content-set/navigation.md‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@ Optional key. Defaults to `false`. When enabled turns soft line endings in the m
4949

5050
### `external_hosts`
5151

52+
% Or remove this section altogether?
53+
```{applies_to}
54+
product: deprecated 0.11.0
55+
```
56+
5257
All links to external hosts must be declared in this section of `docset.yml`.
5358

5459
Example:
@@ -89,6 +94,17 @@ exclude:
8994
- '_*.md'
9095
```
9196

97+
### `products`
98+
99+
Products that are covered in all pages in the doc set.
100+
101+
:::{include} /_snippets/products-list.md
102+
:::
103+
104+
`products` can also be defined in the [page level frontmatter](/syntax/frontmatter.md#products).
105+
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.
106+
You can _not_ override doc set level `products` at the page level.
107+
92108
### `toc`
93109

94110
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.
107123
- folder: subsection
108124
```
109125

110-
If a folder does not explicitly define `children` all markdown files within that folder are included automatically
126+
If a folder does not explicitly define `children` all markdown files within that folder are included automatically
111127

112128
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.
113129

@@ -122,8 +138,8 @@ If a folder does define `children` all markdown files within that folder have to
122138

123139
#### Virtual grouping
124140

125-
A `file` element may include children to create a virtual grouping that
126-
does not match the directory structure.
141+
A `file` element may include children to create a virtual grouping that
142+
does not match the directory structure.
127143

128144
```yaml
129145
...
@@ -137,7 +153,7 @@ A `file` may only select siblings and more deeply nested files as its children.
137153

138154
#### Hidden files
139155

140-
A hidden file can be declared in the TOC.
156+
A hidden file can be declared in the TOC.
141157
```yaml
142158
- hidden: developer-pages.md
143159
```
@@ -176,6 +192,6 @@ See [Attributes](./attributes.md) to learn more.
176192

177193
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.
178194

179-
A `toc.yml` file may only declare a nested [TOC](#toc), other options are ignored.
195+
A `toc.yml` file may only declare a nested [TOC](#toc), other options are ignored.
180196

181197
A `toc.yml` may not link to further nested `toc.yml` files. Doing so will result in an error

‎docs/syntax/frontmatter.md‎

Lines changed: 25 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -43,43 +43,28 @@ See [](./applies.md)
4343
## Products
4444

4545
The products frontmatter is a list of products that the page relates to.
46-
This is used for the "Products" filter in the Search UI.
47-
48-
The products frontmatter is a list of objects, each object has an `id` field.
49-
50-
| Product ID | Product Name |
51-
|---------------------------------------------|-----------------------------------------------|
52-
| `apm` | APM |
53-
| `apm-agent` | APM Agent |
54-
| `auditbeat` | Auditbeat |
55-
| `beats` | Beats |
56-
| `cloud-control-ecctl` | Elastic Cloud Control ECCTL |
57-
| `cloud-enterprise` | Elastic Cloud Enterprise |
58-
| `cloud-hosted` | Elastic Cloud Hosted |
59-
| `cloud-kubernetes` | Elastic Cloud Kubernetes |
60-
| `cloud-serverless` | Elastic Cloud Serverless |
61-
| `cloud-terraform` | Elastic Cloud Terraform |
62-
| `ecs` | Elastic Common Schema (ECS) |
63-
| `ecs-logging` | ECS Logging |
64-
| `edot-cf` | EDOT Cloud Forwarder |
65-
| `edot-sdk` | Elastic Distribution of OpenTelemetry SDK |
66-
| `edot-collector` | Elastic Distribution of OpenTelemetry Collector |
67-
| `elastic-agent` | Elastic Agent |
68-
| `elastic-serverless-forwarder` | Elastic Serverless Forwarder |
69-
| `elastic-stack` | Elastic Stack |
70-
| `elasticsearch` | Elasticsearch |
71-
| `elasticsearch-client` | Elasticsearch Client |
72-
| `filebeat` | Filebeat |
73-
| `fleet` | Fleet |
74-
| `heartbeat` | Heartbeat |
75-
| `integrations` | Integrations |
76-
| `kibana` | Kibana |
77-
| `logstash` | Logstash |
78-
| `machine-learning` | Machine Learning |
79-
| `metricbeat` | Metricbeat |
80-
| `observability` | Elastic Observability |
81-
| `packetbeat` | Packetbeat |
82-
| `painless` | Painless |
83-
| `search-ui` | Search UI |
84-
| `security` | Elastic Security |
85-
| `winlogbeat` | Winlogbeat |
46+
47+
:::{include} /_snippets/products-list.md
48+
:::
49+
50+
`products` can also be defined in the [`docset.yml` file](/configure/content-set/navigation.md#products).
51+
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.
52+
You can _not_ override doc set level `products` at the page level.
53+
54+
:::{tip}
55+
`products` is distinct from `applies_to`, which is used to indicate feature availability and applicability.
56+
57+
% Is this true?
58+
For example, while a page might contain content that is _applicable_ to Elastic Cloud Serverless projects,
59+
it might not be _about_ Elastic Cloud Serverless. In that case, you would include the `serverless` key in `applies_to`,
60+
but _not_ include the `cloud-serverless` ID in `products`:
61+
62+
```yaml
63+
products:
64+
- id: apm
65+
applies_to:
66+
stack: ga
67+
serverless:
68+
observability: ga
69+
```
70+
:::

0 commit comments

Comments
 (0)