Add documentation

Author: cotti

docs/_docset.yml

@@ -76,6 +76,7 @@ toc:
           - file: navigation.md
           - file: versions.md
           - file: legacy-url-mappings.md
+          - file: products.md
       - folder: content-set
         children:
           - file: index.md

docs/configure/site/index.md

@@ -10,6 +10,7 @@ Configure the documentation site in these files:
 - [](./navigation.md) - global navigation index
 - [](./versions.md) - global versioning schemes
 - [](./legacy-url-mappings.md) - supported legacy version
+- [](./products.md) - company product metadata
 
 ## Redirects
 

docs/configure/site/legacy-url-mappings.md

@@ -5,7 +5,9 @@ This [`legacy-url-mappings.yml`](https://github.com/elastic/docs-builder/blob/ma
 This example maps documentation that references `elastic.co/guide/en/elasticsearch/reference/ to Elastic Stack versioned URL paths:
 
 ```yml
-en/elasticsearch/reference/: *stack
+en/elasticsearch/reference/:
+  product: elastic-stack
+  legacy_versions: *stack
 ```
 
 ## Structure
@@ -14,11 +16,7 @@ en/elasticsearch/reference/: *stack
 :   Defines a reusable list of version strings for "stack" projects, e.g., [ '9.0+', '8.18', ... ].
 
 `mappings`
-:   A YAML mapping where each key is a legacy documentation URL path (like `en/apm/agent/java/`) and the value is a list of asciidoc versions that exist for that path.
-
-:::{important}
-The first version in the `mappings` list is treated as the "current" version in documentation version dropdown.
-:::
-
-## Example entry
+:   A YAML mapping where each key is a legacy documentation URL path (like `en/apm/agent/java/`), and each value is a mapping with:
+* `product`: Specifies the product or project type (e.g., `elastic-stack`, `eck`, `ece`, `self-managed`, etc.). Products must be defined in [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml). See [products.yml](./products.md) for more information.
+* `legacy_versions`: A list of version strings that correspond to the available asciidoc pages.
 

docs/configure/site/products.md

@@ -0,0 +1,37 @@
+# `products.yml`
+
+The [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) file specifies metadata regarding the projects in the organization leveraging v3.
+
+```yml
+products:
+  apm-agent-dotnet:
+    display: 'APM Agent for .NET'
+    versioning: 'apm_agent_dotnet'
+  edot-collector:
+    display: 'Elastic Distribution of OpenTelemetry Collector'
+    versioning: 'stack'
+#...
+```
+
+## Structure
+
+`products`
+:   A YAML mapping where each key is an Elastic product.
+* `display`: A friendly name for the product.
+* `versioning`: The versioning system used by the project. The value for this field must match one of the versioning systems defined in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml)
+
+
+
+## Substitutions
+
+The following substitutions are available:
+
+| Substitution | Result |
+| --- |---|
+| `{{ product.apm-agent-dotnet }}` |{{ product.apm-agent-dotnet }}   |
+| `{{ .apm-agent-ios }}` | {{ .apm-agent-ios }} |
+
+## See also
+
+[](./versions.md)
+[](./legacy-url-mappings.md)

docs/syntax/version-variables.md

@@ -82,6 +82,8 @@ This is dictated by the [`versions.yml`](https://github.com/elastic/docs-builder
 * `ech`
 * `eck`
 * `ess`
+* `esf`
+* `search_ui`
 * `self`
 * `ecctl`
 * `curator`
@@ -105,6 +107,17 @@ This is dictated by the [`versions.yml`](https://github.com/elastic/docs-builder
 * `edot_python`
 * `edot_cf_aws`
 * `edot_collector`
+* `apm_attacher`
+* `apm_lambda`
+* `ecs_logging_dotnet`
+* `ecs_logging_go_logrus`
+* `ecs_logging_go_zap`
+* `ecs_logging_go_zerolog`
+* `ecs_logging_java`
+* `ecs_logging_nodejs`
+* `ecs_logging_php`
+* `ecs_logging_python`
+* `ecs_logging_ruby`
 
 The following are available but should not be used. These map to serverless projects and have a fixed high version number.