---
title: products.yml
description: The products.yml file specifies metadata regarding the projects in the organization that use the V3 docs system. Products without a features mapping behave...
url: https://docs-v3-preview.elastic.dev/docs-builder/documentation/catalog/products
products:
  - Elastic Docs Builder
---

# 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 that use the V3 docs system.
```yml
products:
  apm-agent-dotnet:
    display: 'APM .NET Agent'
    versioning: 'apm-agent-dotnet'
  edot-collector:
    display: 'Elastic Distribution of OpenTelemetry Collector'
    versioning: 'stack'
    repository: 'elastic-edot-collector'
  docs-builder:
    display: 'Elastic Docs Builder'
    repository: 'docs-builder'
    features:
      public-reference: false
#...
```


## Structure

<definitions>
  <definition term="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). Optional for products that only participate in release notes.
    - `repository`: The repository name for the product. It's optional and primarily intended for handling edge cases where there is a mismatch between the repository name and the product identifier.
    - `features`: An optional mapping that controls which docs-builder subsystems the product participates in. When omitted, all features are enabled (backward compatible). When present, all features default to `true` and individual features can be opted out by setting them to `false`. The available features are:
    - `public-reference`: The product can be referenced in `applies_to` blocks, page frontmatter `products`, and gets `{{ product.<id> }}` substitutions. This is what "being a documentation product" means today.
    - `release-notes`: The product participates in the changelog and release notes system.
  </definition>
</definitions>

Products without a `features` mapping behave exactly as before -- they participate in all subsystems. The `features` mapping uses opt-out semantics: all features are enabled by default, and you only need to set a feature to `false` to disable it. For example, internal tools that need release notes but don't have public-facing documentation can set `public-reference: false`.
:::

## Substitutions

Writing `{{ product.<product-id> }}` renders the friendly name of the product in the documentation. Substitutions are generated only for products with the `public-reference` feature (or no explicit `features` mapping). For example:

| Substitution                     | Result                                          |
|----------------------------------|-------------------------------------------------|
| `{{ product.apm-agent-dotnet }}` | APM .NET Agent                                  |
| `{{ product.edot-collector }}`   | Elastic Distribution of OpenTelemetry Collector |

You can also use the shorthand notation `{{ .<product_id> }}`. For example:

| Substitution              | Result                                          |
|---------------------------|-------------------------------------------------|
| `{{ .apm-agent-dotnet }}` | APM .NET Agent                                  |
| `{{ .edot-collector }}`   | Elastic Distribution of OpenTelemetry Collector |

<note>
  While the recommended separator is a hyphen (`-`) to promote cohesion, underscores (`_`) are also supported, and internally read as hyphens.
</note>


## See also

[versions.yml](https://docs-v3-preview.elastic.dev/docs-builder/documentation/catalog/versions)
[Legacy URL mappings](https://docs-v3-preview.elastic.dev/docs-builder/documentation/catalog/legacy-url-mappings)