Replace (`::replace, :re`)

We support the following syntax for defining text replacements:

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

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

These replacements can also be defined in other Markdown files included using 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 also be defined in docs/web/config/global-replacements.yaml. They can be cloud-specific or common across all clouds.

info

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

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

warning

It is critical that there are no circular text replacement definitions.

For example, if you were to do the following:

Markdown
::replace[aws]{value=':re[gcp]'}

::replace[gcp]{value=':re[azure]'}

::replace[azure]{value=':re[aws]'}

Hello, this doc should be for :re[aws]

This would yield a circular definition, resulting in build errors.

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 'GCP'. And, due to docs/web/config/global-replacements.yaml, :re[DBR] becomes 'Databricks Runtime'.