Migrate syntax quick ref and contribution pages from docs-builder

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`

contribute-docs/_snippets/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/asciidoc-guide.md

@@ -0,0 +1,41 @@
+---
+navigation_title: Contribute to Asciidoc docs
+---
+
+# Contribute to `elastic.co/guide` (Asciidoc)
+
+To contribute to pages that live at [elastic.co/guide](https://www.elastic.co/guide/index.html), you must work with our [Asciidoc documentation build system](https://github.com/elastic/docs). These docs are written in the [ASCIIDoc](https://asciidoc.org/) markup language.
+
+Refer to [elastic.co/guide](https://www.elastic.co/guide) for the full list of products and versions that use this system.
+
+## Contribute on the web
+
+These changes should be made in the original source folders in their respective repositories. Here's how you can do it:
+
+1. Navigate to the page that is impacted.
+2. Click the **Edit** button.
+3. Ensure the targeted branch is \<insert proper branch\>.
+4. Make the necessary updates.
+5. Commit your changes and create a pull request.
+6. Add the appropriate labels as required by the repo. To learn which labels to add, refer to the contribution documentation for that repo or reach out to the file codeowners.
+
+:::{note}
+Backports can be complicated. You can use the [backport tool](https://github.com/sorenlouv/backport) to manage backporting your changes to other version branches.
+:::
+
+## Contribute locally
+
+For complex or multi-page updates to `elastic.co/guide` (Asciidoc) documentation, refer to the [Asciidoc documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation).
+
+## Updating docs in both systems
+
+If you need to merge changes that are published in both systems (usually because a change is valid in multiple product versions, such as stack 9.x and 8.x), it is recommended to update the documentation in elastic.co/docs first. Then you can convert the updates to ASCIIDoc and make the changes to the elastic.co/guide documentation. To do this, follow these steps:
+
+1. Install [pandoc](https://pandoc.org/installing.html) to convert your markdown file to ASCIIDoc
+2. Update the /docs content first in Markdown as described in [Contribute on the web](on-the-web.md) in the relevant repository.
+3. Run your changes through pandoc:
+   1. If you need to bring over the entire file, you can run the following command and it will create an ASCIIDoc file for you: `pandoc -f gfm -t asciidoc ./<file-name>.md -o <file-name>.asciidoc`
+   2. If you just need to port a specific section you can use: `pandoc -f gfm -t asciidoc ./<file-name>.md` and the output of the file will be in your command window from which you can copy.
+4. Follow the steps in [Contribute on the web](#contribute-on-the-web) to publish your changes.
+5. If the change is too large or complicated, create a new issue in the [`docs-content`](https://github.com/elastic/docs-content) or [`docs-content-internal`](https://github.com/elastic/docs-content-internal) repository detailing the changes made for the team to triage.
+6. Merge the changes and close the issue (if applicable) once the updates are reflected in the documentation.

contribute-docs/how-to/cumulative-docs/_snippets/applies-switch-and-tabs.md

@@ -0,0 +1,6 @@
+:::{tip} - Use applies-switch instead of traditional tabs
+
+When you'd like to build a tabbed experience for content that varies specifically between two or more versions, or between two or more deployment types, prefer using [applies-switch](https://elastic.github.io/docs-builder/syntax/applies-switch) over regular [tabs](https://elastic.github.io/docs-builder/syntax/tabs).
+
+**Applies-switch** natively support using `applies_to` metadata keys as tab titles and offer a more consistent experience with recognizable badges. 
+:::

contribute-docs/how-to/cumulative-docs/_snippets/content-patterns-list.md

@@ -0,0 +1,11 @@
+% | Approach | Use case |
+% | --- | --- |
+% | [Page-level `applies` tags](/versions/example-scenarios.md#page-level-applies-tags) | Provide signals that a page applies to the reader. |
+% | [Section/heading-level `applies` tags](/versions/example-scenarios.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. |
+% | [Tabs](/versions/example-scenarios.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. |
+% | [Callouts](/versions/example-scenarios.md#callouts) | Draw attention to happy differences and basic clarifications. |
+% | [Prose](/versions/example-scenarios.md#prose) | - Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version<br>- List differing requirements, limits, and other simple, mirrored facts<br>- Provide clarifying or secondary information<br>- Explain differences with a "why" (e.g. comparative overviews) |
+% | [Sibling pages](/versions/example-scenarios.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. |
+
+% | [List item suffixes](/versions/example-scenarios.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. |
+% | [Sibling bullets](/versions/example-scenarios.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. |