Merge branch 'main' into georgewallace-patch-8

Author: georgewallace

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "Elastic.elastic-docs-v3-utilities"
+  ]
+}

contribute-docs/_snippets-contribute/guide-intro.md

@@ -0,0 +1,3 @@
+To contribute to `elastic.co/guide` (Asciidoc), you must work with our [Asciidoc documentation build system](https://github.com/elastic/docs). This system uses ASCIIDoc as its markup language.
+
+Docs for {{stack}} 8.x, {{ece}} 3.x, and {{eck}} 2.x can all be found on this site.

contribute-docs/_snippets-contribute/tag-processing.md

@@ -0,0 +1,26 @@
+`applies_to` tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources.
+
+Specifically for versioned products, badges will display differently when the `applies_to` key specifies a product version that has not been released to our customers yet.
+
+The following table shows how badges for versioned products are displayed based on the release status for each lifecycle value. Hover over the example badges for the tooltip text.
+
+| Lifecycle   | Release status | Badge text examples                   |
+|-------------|----------------|---------------------------------------|
+| preview     | prerelease     | {applies_to}`stack: preview 99.99`    |
+|             | post-release   | {applies_to}`stack: preview 9.1`      |
+| beta        | prerelease     | {applies_to}`stack: beta 99.99`       |
+|             | post-release   | {applies_to}`stack: beta 9.1`         |
+| ga          | prerelease     | {applies_to}`stack: ga 99.99`         |
+|             | post-release   | {applies_to}`stack: ga 9.1`           |
+| deprecated  | prerelease     | {applies_to}`stack: deprecated 99.99` |
+|             | post-release   | {applies_to}`stack: deprecated 9.1`   |
+| removed     | prerelease     | {applies_to}`stack: removed 99.99`    |
+|             | post-release   | {applies_to}`stack: removed 9.1`      |
+
+This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml).
+
+When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.
+
+:::{note}
+Visuals and wording in the output documentation are subject to changes and optimizations.
+:::

contribute-docs/_snippets-contribute/tagged-warning.md

@@ -0,0 +1,7 @@
+:::{warning}
+Some repositories use a [tagged branching strategy](https://elastic.github.io/docs-builder/contribute/branching-strategy/), which means that their docs are published from a branch that is not `main` or `master`. In these cases, documentation changes need to be made to `main` or `master`, and then backported to the relevant branches.
+
+For detailed backporting guidance, refer to the example in [Choose the docs branching strategy for a repository](https://elastic.github.io/docs-builder/contribute/branching-strategy/#workflow-2-tagged).
+
+To determine the published branches for a repository, find the repository in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml).
+:::

contribute-docs/_snippets-contribute/two-systems.md

@@ -0,0 +1,7 @@
+Because the new documentation site only hosts documentation for newer releases, the way that you contribute depends on the version that you want to document.
+
+For a list of versions covered on [elastic.co/docs](https://www.elastic.co/docs) (Markdown), refer to [Find docs for your product version](https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version). Versions prior to the versions listed on that page are documented on [elastic.co/guide](https://www.elastic.co/guide). 
+
+:::{tip}
+Unversioned products, such as {{ech}} and {{serverless-full}}, are documented on [elastic.co/docs](https://www.elastic.co/docs).
+:::

contribute-docs/_snippets/applies_to-key.md

@@ -0,0 +1,37 @@
+`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).
+  * `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).
+  * `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started).
+* `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components.
+* `deployment`: Applies to some deployment type(s).
+  * `ece`: Applies to [Elastic Cloud Enterprise](https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise) deployments.
+  * `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 (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).
+  * `apm_agent_node`: Applies to the [Elastic APM Node.js agent](https://www.elastic.co/docs/reference/apm/agents/nodejs).
+  * `apm_agent_php`: Applies to the [Elastic APM PHP agent](https://www.elastic.co/docs/reference/apm/agents/php).
+  * `apm_agent_python`: Applies to the [Elastic APM Python agent](https://www.elastic.co/docs/reference/apm/agents/python).
+  * `apm_agent_ruby`: Applies to the [Elastic APM Ruby agent](https://www.elastic.co/docs/reference/apm/agents/ruby).
+  * `apm_agent_rum`: Applies to the [APM RUM JavaScript agent](https://www.elastic.co/docs/reference/apm/agents/rum-js).
+  * `curator`: Applies to [Elasticsearch Curator](https://www.elastic.co/docs/reference/elasticsearch/curator) (Curator).
+  * `ecctl`: Applies to [Elastic cloud control](https://www.elastic.co/docs/reference/ecctl) (ECCTL).
+  * `edot_android`: Applies to the [Elastic Distribution of OpenTelemetry Android](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/android/) (EDOT Android).
+  * `edot_cf_aws`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/) (EDOT Cloud Forwarder).
+  * `edot_cf_azure`: Applies to the [Elastic Distribution of OpenTelemetry Cloud Forwarder](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/) (EDOT Cloud Forwarder).
+  * `edot_collector`: Applies to the [Elastic Distribution of OpenTelemetry Collector](https://www.elastic.co/docs/reference/opentelemetry/edot-collector/) (EDOT Collector).
+  * `edot_dotnet`: Applies to the [Elastic Distribution of OpenTelemetry .NET](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/dotnet/) (EDOT .NET).
+  * `edot_ios`: Applies to the [Elastic Distribution of OpenTelemetry iOS](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/ios/) (EDOT iOS).
+  * `edot_java`: Applies to the [Elastic Distribution of OpenTelemetry Java](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/java/) (EDOT Java).
+  * `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 `product` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](https://elastic.github.io/docs-builder/syntax/frontmatter#products) is used to drive elastic.co search filters.
+:::

contribute-docs/_snippets/applies_to-lifecycle.md

@@ -0,0 +1,8 @@
+`applies_to` accepts the following lifecycle states:
+
+* `preview`
+* `beta`
+* `ga`
+* `deprecated`
+* `removed`
+* `unavailable`

contribute-docs/_snippets/applies_to-version.md

@@ -0,0 +1,10 @@
+`applies_to` accepts the following version formats:
+
+* `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}
+**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.
+:::

contribute-docs/_snippets/sample-data.csv

@@ -0,0 +1,6 @@
+Name,Age,City,Occupation
+John Doe,30,New York,Software Engineer
+Jane Smith,25,Los Angeles,Product Manager
+Bob Johnson,35,Chicago,Data Scientist
+Alice Brown,28,San Francisco,UX Designer
+Charlie Wilson,32,Boston,DevOps Engineer

contribute-docs/_snippets/stack-serverless-lifecycle-example.md

@@ -0,0 +1,21 @@
+If a change is released in Serverless and will be released in a future version of the {{stack}}, you can add both a `serverless` and `stack` tag, indicating the version of the {{stack}} in which the feature will be released:
+
+```
+---
+applies_to:
+  serverless: ga
+  stack: ga 9.2
+---
+```
+
+Because these changes need to be published as soon as the feature is released in Serverless, you might need to publish your docs before the feature is available in the {{stack}}. To allow for this, Docs V3 [displays badges differently](/contribute-docs/how-to/cumulative-docs/index.md#how-do-these-tags-behave-in-the-output) when the `applies_to` tag specifies a product version that has not yet been released to customers.
+
+* A feature is tagged as available in a current Serverless release and a future {{stack}} version will render the following badges:
+
+    {applies_to}`serverless: ga`
+    {applies_to}`stack: ga 99.99`
+
+* After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source.
+
+    {applies_to}`serverless: ga`
+    {applies_to}`stack: ga 9.0`