docs-builder
Loading

Substitutions

Substitutions can be defined in two places:

  1. In the frontmatter YAML within a file.
  2. Globally for all files in docset.yml

In both cases the yaml to define them is as followed:

subs:
  key: value
  another-var: Another Value

If a substitution is defined globally it may not be redefined (shaded) in a files frontmatter. Doing so will result in a build error.

To use the variables in your files, surround them in curly brackets ({{variable}}).

Here are some variable substitutions:

Variable Defined in
Front Matter Value Front Matter
A key with dashes Front Matter
This was defined in docset.yml docset.yml

Substitutions can be mutated using a chain of operators seperated by a pipe (|).

`{{hello-world | trim | lc | tc}}`

Will trim, lowercase and finally titlecase the contents of the 'hello-world' variable.

Operator Purpose
lc LowerCase,
uc UpperCase,
tc TitleCase, capitalizes all words,
c Capitalize the first letter,
kc Convert to KebabCase,
sc Convert to SnakeCase,
cc Convert to CamelCase,
pc Convert to PascalCase,
trim Trim common non word characters from start and end

For variables declaring a semantic version or Major.Minor the following operations are also exposed

Operator Purpose
M Display only the major component
M.x Display major component followed by '.x'
M.M Display only the major and the minor
M+1 The next major version
M.M+1 The next minor version

Given the following frontmatter:

---
sub:
  hello-world: "Hello world!"
---
  • Lowercase: hello world!
  • Uppercase: HELLO WORLD!
  • TitleCase: Hello World!
  • kebab-case: hello-world!
  • camelCase: helloWorld!
  • PascalCase: HelloWorld!
  • SnakeCase: hello_world!
  • CapitalCase (chained): Hello world!
  • Trim: Hello world
  • M.x: 9.x
  • M.M: 9.0
  • M: 9
  • M+1: 10.0.0
  • M+1 | M.M: 10.0
  • M.M+1: 9.1.0
* Lowercase: {{hello-world | lc}}
* Uppercase: {{hello-world | uc}}
* TitleCase: {{hello-world | tc}}
* kebab-case: {{hello-world | kc}}
* camelCase: {{hello-world | tc | cc}}
* PascalCase: {{hello-world | pc}}
* SnakeCase: {{hello-world | sc}}
* CapitalCase (chained): {{hello-world | lc | c}}
* Trim: {{hello-world | trim}}
* M.x: {{version.stack | M.x }}
* M.M: {{version.stack | M.M }}
* M: {{version.stack | M }}
* M+1: {{version.stack | M+1 }}
* M+1 | M.M: {{version.stack | M+1 | M.M }}
* M.M+1: {{version.stack | M.M+1 }}

Substitutions are supported in code blocks but are disabled by default. Enable substitutions by adding subs=true to the code block.

```bash subs=true
# Your code with variables
```

wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.17.0-linux-x86_64.tar.gz
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.17.0-linux-x86_64.tar.gz.sha512
shasum -a 512 -c elasticsearch-7.17.0-linux-x86_64.tar.gz.sha512
tar -xzf elasticsearch-7.17.0-linux-x86_64.tar.gz
cd elasticsearch-7.17.0/

```{code} sh subs=true
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{{version}}-linux-x86_64.tar.gz
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{{version}}-linux-x86_64.tar.gz.sha512
shasum -a 512 -c elasticsearch-{{version}}-linux-x86_64.tar.gz.sha512
tar -xzf elasticsearch-{{version}}-linux-x86_64.tar.gz
cd elasticsearch-{{version}}/
```

echo "This was defined in docset.yml"

```bash subs=true
echo "{{a-global-variable}}"
```

echo "{{a-global-variable}}"

```bash
echo "{{a-global-variable}}"
```