Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Last updated on

Replace (::replace, :re)

↑ Docs content model

The replace atom defines a text replacement (::replace) and inlines it (:re), so a single token renders as different text depending on context (for example, per cloud).

When to use​

Use replacements for terms that vary by cloud or product, or for values that should be defined once and reused — cloud names, product names, runtime versions. Global replacements live in docs/web/config/global-replacements.yaml; define local ones with ::replace when a replacement applies only to one page.

Technical details​

Markdown
::replace[<replace-text>]{value='<replacement-value>'}

In content, :re[<replace-text>] gets replaced.

Replacements can also be defined in other Markdown files pulled in with include directives, or inside cloud directives for different replacements per cloud.

In addition to locally defined replacements via ::replace, global replacements (affecting all Markdown files) can be defined in docs/web/config/global-replacements.yaml. They can be cloud-specific or common across all clouds.

If multiple different replacements are defined for the same <replace-text>, the earliest one in this prioritized list is used:

  1. Locally defined replacement (prioritizing the one defined latest in the Markdown file)
  2. Cloud-specific global replacement in docs/web/config/global-replacements.yaml
  3. Common (non-cloud-specific) global replacement in docs/web/config/global-replacements.yaml

Rules​

  • ::replace requires a value attribute.
  • No circular definitions: a chain of replacements must not resolve back to itself. Circular replacements cause build errors.
  • When the same token has multiple definitions, resolution follows the priority order above (local → cloud-specific global → common global).

Style​

  • Prefer global replacements for terms used across the docs set; reserve local ::replace for page-specific values.

Template​

Markdown
::replace[token]{value='replacement value'}

In content, :re[token] becomes the value.

Examples​

Example:

Markdown
`:re[value]` becomes ':re[value]'. Due to cloud directives, `:re[cloud]` depends on the current cloud and becomes ':re[cloud]'. And, due to `docs/web/config/global-replacements.yaml`, `:re[DBR]` becomes ':re[DBR]'.

::replace[value]{value='replaced value'}

:::aws

::replace[cloud]{value='AWS'}

:::

:::gcp

::replace[cloud]{value='GCP'}

:::

:::sap

::replace[cloud]{value='SAP'}

:::

:::azure

::replace[cloud]{value='AZURE'}

:::

Output:

:re[value] becomes 'replaced value'. Due to cloud directives, :re[cloud] depends on the current cloud and becomes 'AWS'. And, due to docs/web/config/global-replacements.yaml, :re[DBR] becomes 'Databricks Runtime'.

Used in​

Content atoms appear in any page section. Replacement tokens appear throughout every section, wherever cloud- or product-specific terms are used.

On this page