diff --git a/docs/_snippets/applies_to-key.md b/docs/_snippets/applies_to-key.md index b3a6d57a0..a8f8729ec 100644 --- a/docs/_snippets/applies_to-key.md +++ b/docs/_snippets/applies_to-key.md @@ -1,4 +1,4 @@ -`applies_to` accepts the following keys in this structure: +`applies_to` accepts the following keys in this structure. * `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless). * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project). @@ -10,7 +10,7 @@ * `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments. * `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments. * `ess`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments. -* `product`: Applies to a specific product that uses a unique versioning scheme (e.g. not `stack`, `ece`, `eck`). +* `product`: Applies to a specific product that uses a unique versioning scheme (for example, not `stack`, `ece`, `eck`). * `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet). * `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go). * `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java). @@ -30,7 +30,7 @@ * `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/) (EDOT Node.js). * `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/) (EDOT PHP). * `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/) (EDOT Python). - + :::{note} -The `products` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters. +The `product` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters. ::: diff --git a/docs/_snippets/applies_to-version.md b/docs/_snippets/applies_to-version.md index 64d72cd7f..f98f758d0 100644 --- a/docs/_snippets/applies_to-version.md +++ b/docs/_snippets/applies_to-version.md @@ -3,7 +3,8 @@ * `Major.Minor` * `Major.Minor.Patch` +Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format. + :::{note} -Regardless of the version format used in the source file, -the version number will always be rendered in the `Major.Minor.Patch` format. -::: +**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last. +::: \ No newline at end of file diff --git a/docs/contribute/cumulative-docs/badge-placement.md b/docs/contribute/cumulative-docs/badge-placement.md index 539a7aafd..abd5cdc5e 100644 --- a/docs/contribute/cumulative-docs/badge-placement.md +++ b/docs/contribute/cumulative-docs/badge-placement.md @@ -38,15 +38,15 @@ There are more specific guidelines on badge placement to follow when using speci ### Page frontmatter -Use [`applies_to` in a page's frontmatter](/syntax/applies.md#page-annotations) to provide signals that a page applies to the reader. +Use [`applies_to` in a page's frontmatter](/syntax/applies.md#syntax) to provide signals that a page applies to the reader. ::::{warning} -Do **not** use [section-level](/syntax/applies.md#section-annotations) or [inline annotations](/syntax/applies.md#inline-annotations) with the page title. +Do **not** use [section-level](/syntax/applies.md#section-level) or [inline annotations](/syntax/applies.md#inline-level) with the page title. :::: ### Headings [headings] -Use [section annotations](/syntax/applies.md#section-annotations) on the next line after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific. +Use [section annotations](/syntax/applies.md#section-level) on the next line after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific. For example, on the [Observability AI Assistant](https://www.elastic.co/docs/solutions/observability/observability-ai-assistant#choose-the-knowledge-base-language-model) page, all the content in this section is only applicable to Elastic Stack versions 9.1.0 and later. @@ -58,7 +58,7 @@ For example, on the [Observability AI Assistant](https://www.elastic.co/docs/sol % FOR THE REVIEWER: IS THIS TRUE? % What do you think of allowing inline applies_to in headings as long as there is only one badge? :::{warning} -Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with headings. +Do **not** use [inline annotations](/syntax/applies.md#inline-level) with headings. ::::{image} ./images/heading-incorrect.png :screenshot: diff --git a/docs/syntax/_snippets/inline-level-applies-examples.md b/docs/syntax/_snippets/inline-level-applies-examples.md new file mode 100644 index 000000000..37645fbe5 --- /dev/null +++ b/docs/syntax/_snippets/inline-level-applies-examples.md @@ -0,0 +1,73 @@ +::::::{dropdown} Basic example + +:::::{tab-set} + +::::{tab-item} Output + +**Spaces** let you organize your content and users according to your needs. + +- Each space has its own saved objects. +- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. + +:::: + +::::{tab-item} Markdown +```markdown +**Spaces** let you organize your content and users according to your needs. + +- Each space has its own saved objects. +- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. +``` +:::: + +::::: + +:::::: + +::::::{dropdown} Product-specific applicability with version information + +This example shows how to use directly a key from the second level of the `applies_to` data structure, like `edot_python:`. + +:::::{tab-set} + +::::{tab-item} Output + +- {applies_to}`edot_python: preview 1.7.0` +- {applies_to}`apm_agent_java: beta 1.0.0` + +:::: + +::::{tab-item} Markdown +```markdown +- {applies_to}`edot_python: preview 1.7.0` +- {applies_to}`apm_agent_java: beta 1.0.0` +``` +:::: + +::::: + +:::::: + +::::::{dropdown} Multiple products and states in a single inline statement + +:::::{tab-set} + +::::{tab-item} Output + +- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0` +- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0` +- {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0` + +:::: + +::::{tab-item} Markdown +```markdown +- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0` +- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0` +- {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0` +``` +:::: + +::::: +:::::: + diff --git a/docs/syntax/_snippets/line-level-applies-example.md b/docs/syntax/_snippets/line-level-applies-example.md deleted file mode 100644 index b695ed9e0..000000000 --- a/docs/syntax/_snippets/line-level-applies-example.md +++ /dev/null @@ -1,7 +0,0 @@ -````markdown -**Spaces** let you organize your content and users according to your needs. - -- Each space has its own saved objects. -- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. -```` -% I think we wanted to not specify stack here diff --git a/docs/syntax/_snippets/page-level-applies-examples.md b/docs/syntax/_snippets/page-level-applies-examples.md index a65cf3f9f..5c3f7fe28 100644 --- a/docs/syntax/_snippets/page-level-applies-examples.md +++ b/docs/syntax/_snippets/page-level-applies-examples.md @@ -1,16 +1,16 @@ -There are 3 typical scenarios to start from: +:::::{dropdown} Document is primarily about using or interacting with Elastic Stack components or the Serverless UI -* The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI: + ```yml + --- + applies_to: + stack: ga + serverless: ga + --- + ``` - ```yml - --- - applies_to: - stack: ga - serverless: ga - --- - ``` +::::: -* The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys): +:::::{dropdown} Document is primarily about orchestrating, deploying or configuring an installation ```yml --- @@ -24,7 +24,9 @@ There are 3 typical scenarios to start from: ``` -* The documentation set or page is primarily about a product following its own versioning schema: +::::: + +:::::{dropdown} Document is primarily about a product following its own versioning schema ```yml --- @@ -33,21 +35,4 @@ There are 3 typical scenarios to start from: --- ``` -It can happen that it’s relevant to identify several or all of these dimensions for a page. Use your own judgement and check existing pages in similar contexts. - -```yml ---- -applies_to: - stack: ga - serverless: ga - deployment: - ess: ga - ece: ga - eck: ga ---- -``` -% I don't know what this example is supposed to show - - - - +::::: diff --git a/docs/syntax/_snippets/section-level-applies-examples.md b/docs/syntax/_snippets/section-level-applies-examples.md index 97dc1eec0..4a9d71b76 100644 --- a/docs/syntax/_snippets/section-level-applies-examples.md +++ b/docs/syntax/_snippets/section-level-applies-examples.md @@ -1,40 +1,41 @@ -* The whole page is generally applicable to {{stack}} 9.0 and to {{serverless-short}}, but one specific section isn’t applicable to {{serverless-short}} (and there is no alternative for it): - - ````md - --- - applies_to: - stack: ga - serverless: ga - --- - - # Spaces - - [...] - - ## Configure a space-level landing page [space-landing-page] - ```{applies_to} - serverless: unavailable - ``` - ```` - % I think we wanted to not specify stack here - -* The whole page is generally applicable to all deployment types, but one specific paragraph only applies to {{ech}} and {{serverless-short}}, and another paragraph only applies to {{ece}}: - - ````md - ## Cloud organization level security [cloud-organization-level] - ```{applies_to} - deployment: - ess: ga - serverless: ga - ``` - - [...] - - ## Orchestrator level security [orchestrator-level] - ```{applies_to} - deployment: - ece: ga - ``` - - [...] - ```` \ No newline at end of file +:::::{dropdown} Applicable to Stack and Serverless, minus a section + +````markdown +--- +applies_to: +stack: ga +serverless: ga +--- + +# Spaces + +[...] + +#### Configure a space-level landing page [space-landing-page] +```{applies_to} +serverless: unavailable +``` +```` +::::: + +:::::{dropdown} Applicable to all deployment types, but some paragraphs are specific to other deployment types + +````markdown +#### Cloud organization level security [cloud-organization-level] +```{applies_to} +serverless: ga +deployment: + ess: ga +``` + +[...] + +#### Orchestrator level security [orchestrator-level] +```{applies_to} +deployment: + ece: ga +``` + +[...] +```` +::::: \ No newline at end of file diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 77be6d5d7..bfd8feb54 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,9 +1,5 @@ # Applies to - - Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](/contribute/cumulative-docs/index.md): instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time. To support this, source files use a tagging system to indicate: @@ -11,173 +7,188 @@ To support this, source files use a tagging system to indicate: * Which Elastic products and deployment models the content applies to. * When a feature changes state relative to the base version. -This is what the `applies_to` metadata is for. It can be used at the [page](#page-annotations), -[section](#section-annotations), or [inline](#inline-annotations) level to specify applicability with precision. +This is what the `applies_to` metadata is for. It can be used at the [page](#page-level), +[section](#section-level), or [inline](#inline-level) level to specify applicability with precision. -**For detailed guidance, refer to [](/contribute/cumulative-docs/index.md).** +:::{note} +For detailed guidance, refer to [](/contribute/cumulative-docs/index.md). +::: ## Syntax -The `applies_to` metadata supports an [exhaustive list of keys](#key). +The `applies_to` metadata supports an [exhaustive list of keys](#key-value-reference). -When you write or edit documentation, only specify the keys that apply to that content. -Each key accepts values with the following syntax: +When you write or edit documentation, only specify the keys that apply to that content. Each key accepts values with the following syntax: ``` -: [version] +: [version], [version], ... ``` Where: -- The [lifecycle](#lifecycle) is mandatory -- The [version](#version) is optional -- You can specify multiple states by separating them with a comma. For example: `stack: preview 9.1, ga 9.4` - -:::{note} -**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last. -::: +- The lifecycle is mandatory. +- The version is optional. -Note that a key without any value doesn't show any badge in the output. +### Page level -Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): +Page level annotations are added in the YAML frontmatter, starting with the `applies_to` key and following the [key-value reference](#key-value-reference). For example: -``` +```yaml +--- applies_to: - stack: preview 9.1, ga 9.4 + stack: ga deployment: - ece: deprecated 9.2, removed 9.8 + ece: ga +--- ``` -Unversioned products use `lifecycle` tags without a version: +For more examples, refer to [Page annotation examples](#page-annotation-examples). + +:::{important} +All documentation pages must include an `applies_to` tag in the YAML frontmatter. +::: +### Section level + +A header can be followed by an `{applies_to}` directive which contextualizes the applicability of the section further. + +Section-level `{applies_to}` directives require triple backticks because their content is literal. Refer to [](index.md#literal-directives) for more information. + +````markdown +```{applies_to} +stack: ga 9.1 ``` -applies_to: - serverless: - elasticsearch: beta - observability: removed +```` + +To play even better with Markdown editors the following is also supported: + +````markdown +```yaml {applies_to} +stack: ga 9.1 ``` +```` -### Key +This allows the YAML inside the `{applies_to}` directive to be fully highlighted. -:::{include} /_snippets/applies_to-key.md +For more examples, refer to [Section annotation examples](#section-annotation-examples). + +:::{note} +Section-level `{applies_to}` directives must be preceded by a heading directly. ::: -### Lifecycle +### Inline level -:::{include} /_snippets/applies_to-lifecycle.md -::: +You can add inline applies annotations to any line using the following syntax: -### Version +```markdown +This can live inline {applies_to}`section: [version]` +``` -:::{include} /_snippets/applies_to-version.md -::: +A specialized `{preview}` role exists to quickly mark something as a technical preview. It takes a required version number +as an argument. +```markdown +Property {preview}`` +: definition body +``` -## Examples +For more examples, refer to [Inline annotation examples](#inline-annotation-examples). -### Lifecycle examples +## Key-value reference -#### Unversioned products +Use the following key-value reference to find the appropriate key and value for your applicability statements. -:::{include} _snippets/unversioned-lifecycle.md -::: +:::::{tab-set} -#### Versioned products +::::{tab-item} Keys -:::{include} _snippets/versioned-lifecycle.md +:::{include} /_snippets/applies_to-key.md ::: -#### Identify multiple states for the same content +:::: -:::{include} /syntax/_snippets/multiple-lifecycle-states.md -::: +::::{tab-item} Lifecycles -### Page annotations +:::{include} /_snippets/applies_to-lifecycle.md +::: -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment target's availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). +:::: -#### Page annotation examples +::::{tab-item} Versions -:::{include} _snippets/page-level-applies-examples.md +:::{include} /_snippets/applies_to-version.md ::: -### Section annotations - -```yaml {applies_to} -stack: ga 9.1 -deployment: - eck: ga 9.0 - ess: beta 9.1 - ece: deprecated 9.2.0 -serverless: - security: unavailable - elasticsearch: beta - observability: deprecated -product: preview 9.5, deprecated 9.7 -``` +:::: +::::: -A header may be followed by an `{applies_to}` directive which will contextualize the applicability -of the section further. +## Examples -:::{note} -the `{applies_to}` directive **MUST** be preceded by a heading directly. -::: +### Versioning examples -Note that this directive requires triple backticks since its content is literal. See -also [](index.md#literal-directives) +Versioned products require a `version` tag to be used with the `lifecycle` tag: -````markdown -```{applies_to} -stack: ga 9.1 ``` -```` +applies_to: + stack: preview 9.1, ga 9.4 + deployment: + ece: deprecated 9.2, removed 9.8 +``` -In order to play even better with markdown editors the following is also supported: +Unversioned products use `lifecycle` tags without a version: -````markdown -```yaml {applies_to} -stack: ga 9.1 ``` -```` +applies_to: + serverless: + elasticsearch: beta + observability: removed +``` -This will allow the YAML inside the `{applies_to}` directive to be fully highlighted. +### Lifecycle and versioning examples -#### Section annotation examples +:::::{dropdown} Unversioned products -:::{include} _snippets/section-level-applies-examples.md +:::{include} _snippets/unversioned-lifecycle.md ::: -### Inline annotations +::::: -Inline applies to can be placed anywhere using the following syntax +:::::{dropdown} Versioned products -```markdown -This can live inline {applies_to}`section: [version]` -``` +:::{include} _snippets/versioned-lifecycle.md +::: -An inline version example would be {applies_to}`stack: beta 9.1` this allows you to target elements more concretely -visually. +::::: -#### Inline annotation examples +:::::{dropdown} Identify multiple states for the same content -* The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative): +:::{include} /syntax/_snippets/multiple-lifecycle-states.md +::: - :::{include} _snippets/line-level-applies-example.md - ::: +::::: -A specialized `{preview}` role exists to quickly mark something as a technical preview. It takes a required version number -as an argument. +### Page annotation examples -```markdown -Property {preview}`` -: definition body -``` +:::{include} _snippets/page-level-applies-examples.md +::: + +### Section annotation examples + +:::{include} _snippets/section-level-applies-examples.md +::: + +### Inline annotation examples + +:::{include} _snippets/inline-level-applies-examples.md +::: ## Structured model ![Applies To Model](images/applies.png) -The above model is projected to the following structured YAML. +The previous model is projected to the following structured YAML. + +:::::{dropdown} Applies to model ```yaml --- @@ -214,12 +225,14 @@ applies_to: edot_cf_aws: --- ``` - +::::: ## Look and feel ### Block +:::::{dropdown} Block examples + ```{applies_to} stack: preview 9.1 serverless: ga @@ -233,10 +246,11 @@ elasticsearch: preview 9.0.0 security: removed 9.0.0 observability: deprecated 9.0.0 ``` +::::: ### Inline -#### In text +:::::{dropdown} In text Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. {applies_to}`stack: preview` Aenean scelerisque viverra lectus @@ -246,7 +260,9 @@ nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictu - {applies_to}`observability: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. - {applies_to}`security: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Aenean scelerisque viverra lectus nec dignissim. -#### Stack +::::: + +:::::{dropdown} Stack | `applies_to` | result | |--------------------------------------------|--------------------------------------| @@ -276,8 +292,9 @@ nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictu | `` {applies_to}`stack: removed 9.0` `` | {applies_to}`stack: removed 9.0` | | `` {applies_to}`stack: removed 9.1` `` | {applies_to}`stack: removed 9.1` | | `` {applies_to}`stack: removed 99.0` `` | {applies_to}`stack: removed 99.0` | +::::: -#### Serverless +:::::{dropdown} Serverless | `applies_to` | result | |-------------------------------------------------|-------------------------------------------| @@ -287,6 +304,7 @@ nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictu | `` {applies_to}`serverless: beta` `` | {applies_to}`serverless: beta` | | `` {applies_to}`serverless: deprecated` `` | {applies_to}`serverless: deprecated` | | `` {applies_to}`serverless: removed` `` | {applies_to}`serverless: removed` | +::::: ### Badge rendering order @@ -298,4 +316,8 @@ nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictu 4. **ProductApplicability** - Specialized tools and agents (ECCTL, Curator, EDOT, APM Agents) 5. **Product (generic)** - Generic product applicability -Within the ProductApplicability category, EDOT and APM Agent items are sorted alphabetically for easy scanning. \ No newline at end of file +Within the ProductApplicability category, EDOT and APM Agent items are sorted alphabetically for better scanning. + +:::{note} +Inline applies annotations are rendered in the order they appear in the source file. +::: \ No newline at end of file diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index d7eba94c0..e8f532566 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -145,8 +145,8 @@ The `applies_to` tags are scope signals for readers, not comprehensive metadata. % TODO restore details when guidance has settled **DOs**
-✅ **Do:** Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
-✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#section-annotations) after a heading
+✅ **Do:** Define a set of [page-level tags](applies.md#page-level) in a front matter block
+✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#section-level) after a heading
✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` **DON'Ts**