ReferenceBuilt-in steps
replace
Replaces literal tokens in pages, code blocks included, with values rendered from their data.
The replace step replaces literal tokens in the content of each page, code blocks included, with values rendered
from the page's data. It runs before Liquid, so it also reaches the fenced code blocks that Liquid leaves alone, for
instance to write the current version in installation commands.
| Shape | map (no group-by) |
Default match |
**/*.md, **/*.html |
| Default workflow | no |
What it doesLink to this heading
For each text file it consumes, the step looks for every token of tokens, in the order they are listed, with an
ordinal (exact, case sensitive) search. For each token the file contains, it renders the token's value as a Liquid
template with the file's data, and replaces every occurrence of the token with the result. Tokens the file does not
contain are not rendered.
A file that contains no token, a binary file, and a file that skip matches pass through unchanged.
OptionsLink to this heading
| Option | Type | Default | Meaning |
|---|---|---|---|
tokens |
mapping of strings to strings | required | Each token and its value, a Liquid template rendered with the file's data ("%VERSION%": "{{ versions.current }}"). Numbers and booleans are used as text |
skip |
glob or list of globs | none | Files that pass through without replacements |
CachingLink to this heading
A file depends on the data its token values read, and only when it contains the token: changing the version renders
again the pages that contain %VERSION%, not the others.
ErrorsLink to this heading
douze.yml(4,3): error: step 'versions' needs the option 'tokens', a mapping of tokens to values
douze.yml(4,3): error: option 'tokens' of step 'versions' has an empty token
douze.yml(4,3): error: the value of token '%VERSION%' of step 'versions' must be a string
ExampleLink to this heading
site:
data: data
steps:
site-data:
inputs: "data/*.yml"
uses: data
with:
scope: site
pages:
inputs: "docs/**/*.md"
needs: site-data
uses: frontmatter
versions:
needs: pages
uses: replace
with:
tokens:
"%VERSION%": "{{ release.current }}"
skip: "docs/release-notes/**"
permalink:
needs: versions
uses: permalink
render:
needs: permalink
uses: liquid
markdown:
needs: render
uses: markdown
write:
needs: markdown
uses: write
With data/release.yml containing current: 2.1.0, a page with
```bash
dotnet add package Contoso --version %VERSION%
```
renders dotnet add package Contoso --version 2.1.0.