ReferenceReference
douze.yml
The full schema of douze.yml, the site, markdown and steps sections, with defaults and validation errors.
douze.yml at the root of the source folder, or the file given with -w, configures a site. It is a mapping with
four optional sections: site, vars, markdown and steps. A site without the file, or a file without steps, builds
with the default workflow. An empty file is the same as no file.
site:
content: docs
url: https://example.com
vars:
og: true
markdown:
extensions: [pipetables, footnotes, alerts, customcontainers, attributes]
steps:
site-data:
inputs: "_data/*.json"
uses: data
with:
scope: site
pages:
inputs: "docs/**"
needs: site-data
uses: frontmatter
permalink:
needs: pages
uses: permalink
with:
root: docs
render:
needs: permalink
uses: liquid
markdown:
needs: render
uses: markdown
layout:
needs: markdown
uses: layout
write:
needs: layout
uses: write
Any other top-level key is an error: unknown key 'foo'; expected 'site', 'vars', 'markdown' or 'steps'.
siteLink to this heading
The folders of the site and the values every template sees under site.
| Key | Type | Default | Meaning |
|---|---|---|---|
content |
folder | _content if it exists, else the source folder |
Pages, folder data files and any other file to publish. |
data |
folder | _data if it exists, else none |
Site data files. |
includes |
folder | _includes if it exists, else the source folder |
Layouts, includes and templates. |
shortcodes |
folder | shortcodes in the includes folder |
Shortcode templates. |
output |
folder | _site in the current folder |
The output folder, relative to the source folder. -o wins. |
url |
string | none | The site's url: site.url in templates, used by absolute_url and relative_url. |
parallelism |
positive integer | the processor count | The maximum number of units that run at once. -p wins. |
locales |
mapping | none | The locales of the site, see locales. |
Folders are relative to the source folder and must stay inside it (no ..). The output folder, the cache folder and
.douze are never sources when they are inside the source folder.
site.url is merged with the site data named site (_data/site.json): a template can read site.title from the
data file and site.url from douze.yml, unless the data file defines url too. See
template data.
site:
content: docs
data: data
includes: templates
shortcodes: templates/components
output: public
url: https://example.com
parallelism: 8
site.localesLink to this heading
site:
locales:
default: en
root: docs
fallback: true
strings: i18n
languages:
en:
label: English
ja:
label: 日本語
lang: ja
ar:
label: العربية
lang: ar
dir: rtl
| Key | Type | Default | Meaning |
|---|---|---|---|
default |
locale folder name | required | The locale whose pages have no url prefix. |
root |
folder | the content folder | The folder, relative to the content folder, whose subfolders are the locales. |
fallback |
true or false |
false |
The localize step copies the default locale's untranslated pages under every other locale. |
strings |
string | i18n |
The site data of the UI strings for the t filter: _data/i18n/en.yml, _data/i18n/ja.yml. |
languages |
mapping | none | The locale folders, each with its settings. The default locale may be listed for its settings; it has no folder. |
Each language takes:
| Key | Default | Meaning |
|---|---|---|
label |
the key | The name shown in a language switcher. |
lang |
the key | The lang attribute value. |
dir |
ltr |
ltr or rtl. |
A page of docs/ja/ is a page of ja, any other page under docs a page of en. Templates see the settings as
site.locales: default, fallback, strings and languages, the list of every locale (locale, label, lang,
dir, prefix), the default first. See Internationalization.
varsLink to this heading
The variables of the site, with their default values. Templates read them as vars.<name>, and so do the
enabled expressions of the steps, wherever the section is in the file.
vars:
og: true
label: Preview
posts: 10
Each of these sets the variables, over the previous one:
- The
varssection. - The environment variables
DOUZE_VARS__<name>:DOUZE_VARS__og=false. - The
--var <name>=<value>and--env <name>=<variable>options of the command line, in order.--envreads the value of an environment variable, and does nothing when it is not set.
Only declared variables can be set, and their names match case insensitively: --var OG=false sets og. A value
takes the type of the default:
| Default | A value set from outside is |
|---|---|
true or false |
a boolean: true or false, in any case |
| an integer | an integer |
| a number with decimals | a number |
a string, or ~ |
the string as written |
| a mapping or a list | an error: objects and lists can only be set in the section |
So --var og=false is the boolean false, which a template or an enabled expression treats as false (the string
"false" would be true in Liquid). vars: without a value declares no variable.
| Error | Cause |
|---|---|
'vars' must be a mapping of names to values |
vars is a list or a scalar. |
unknown variable '<name>' in '--var <name>'; declare it in 'vars' |
A variable that the section does not declare, also from --env or a DOUZE_VARS__ environment variable. |
variable 'og' must be true or false, not 'maybe' ('--var og') |
A value of the wrong type; must be an integer, must be a number. With --env, the value is not shown. |
variable '<name>' is a list and cannot be set by '--var <name>' |
Also for a mapping (is an object). |
markdownLink to this heading
How Markdown renders, for the markdown step and everything else that renders Markdown (the
markdownify filter, include_markdown, shortcode bodies). Without the section, Markdown is CommonMark without
extensions. markdown: without a value is the same as no section.
markdown:
extensions: [pipetables, footnotes, tasklists, definitionlists, attributes, autolinks, alerts, customcontainers]
aside:
tag: aside
class: aside
kinds: [note, tip, caution, danger]
titles:
note: Note
links: true
code:
class-prefix: language-
passthrough: [mermaid]
images:
widths: [640, 1280]
formats: [webp]
quality: 80
output: assets/images
loading: lazy
| Key | Type | Default | Meaning |
|---|---|---|---|
extensions |
string or list | [pipetables, footnotes, tasklists, definitionlists, attributes, autolinks, alerts, customcontainers] |
Markdig extensions, applied in order but attributes last. |
aside |
mapping | see below | How :::note containers and > [!NOTE] alerts render. |
links |
true or false |
true |
Relative links to .md files of the content folder become the urls of their pages. |
code.class-prefix |
string | language- |
The prefix of the language class of a fence's code element. |
code.passthrough |
string or list | [mermaid] |
Fence languages rendered as <pre class="mermaid"> without code, for a client script. |
images |
mapping | see below | The defaults of the image features. |
extensionsLink to this heading
The names are Markdig's: common, advanced, alerts, pipetables, gfm-pipetables, emphasisextras,
listextras, hardlinebreak, footnotes, footers, citations, attributes, gridtables, abbreviations,
emojis, definitionlists, customcontainers, figures, mathematics, bootstrap, medialinks, smartypants,
tasklists, diagrams, nofollowlinks, noopenerlinks, noreferrerlinks, nohtml, yaml, nonascii-noescape,
autolinks, globalization, cjk-friendly-emphasis, plus none, and strikethrough, Douze's emphasisextras
without subscript, superscript, inserted and marked text. advanced is Markdig's set without autoidentifiers:
heading ids are the headings step's.
| Error | Cause |
|---|---|
unknown Markdown extension 'tabels'; did you mean 'pipetables'? |
An unknown name; common other spellings (tables, admonitions, math) suggest the right one. |
use the headings step for heading ids |
autoidentifiers. |
The extensions option of a markdown step replaces the extensions for that step and keeps the other settings.
asideLink to this heading
| Key | Default | Meaning |
|---|---|---|
tag |
aside |
The element. |
class |
aside |
The block class; <class>--<kind>, <class>__title and <class>__content derive from it. |
kinds |
[note, tip, caution, danger] |
The known kinds. Another kind renders as the first, with a warning. |
titles |
Note, Tip, Caution, Danger |
The default title per kind; a kind without one is its name, capitalized. |
icons |
none | Markup (an inline SVG) written before the title, per kind. |
titles-from |
none | Read and validated, not used yet. |
A :::note container renders as:
<aside aria-label="Note" class="aside aside--note"><p class="aside__title" aria-hidden="true">Note</p><div class="aside__content">...</div></aside>
:::tip[Before you start] sets the title. The alerts IMPORTANT and WARNING are note and caution. titles and
icons keys must be kinds of kinds.
imagesLink to this heading
The defaults of the image tag, the image_url filter and the images and
pictures steps.
| Key | Type | Default | Meaning |
|---|---|---|---|
widths |
list of positive integers | the source's width | The widths of the variants. |
formats |
string or list | the source's format | webp, avif, png, jpeg. |
quality |
integer, 1 to 100 | 80 |
The quality of lossy formats. |
output |
folder | /assets/images/ |
The folder of the variants. |
loading |
lazy or eager |
lazy |
The loading attribute of the <img>. |
stepsLink to this heading
steps maps step names to steps. Source files enter the steps whose inputs match them; the files that come out of
a step enter the steps that need it. A step consumes the entering files its match selects; the others pass
through it unchanged. Steps run as soon as their files are available, in parallel, so their order in the file does not
matter. steps: without a value is the default workflow. See Workflow architecture.
Step names are lowercase letters, digits and dashes, start with a letter, and have at most 64 characters. source is
reserved.
A step has either uses (a built-in step) or run (a command).
| Field | Type | Default | Meaning |
|---|---|---|---|
inputs |
glob or list | none | The source files that enter this step, relative to the source folder. |
needs |
step name or list | none | The steps whose output files, and data, enter this step. |
match |
glob or list | the step's own | The entering files the step consumes. The others pass through. |
uses |
built-in step name | The built-in step to run. | |
with |
mapping | none | The options of the built-in step, or for mode: worker, the options sent to the worker. |
group-by |
file, dir or a Liquid template |
none | Processes the files in groups, one unit per group. Only some steps support it (liquid, batch commands). |
incremental |
true or false |
true |
false runs the step on every build instead of reusing cached results. |
enabled |
true, false or a Liquid expression |
true |
A step that is not enabled is left out: the steps that need it need what it needs instead. |
run |
string | The command line of a command step. | |
tool |
name or name@version |
A tool Douze downloads for the command. | |
mode |
filter, batch or worker |
batch |
How files reach the command. |
outputs |
glob or list | every file | Batch only: the files read back from the outputs folder. |
sources |
glob or list | none | Files whose content is part of the command's cache key (its scripts). |
version |
string | empty | Part of the command's cache key: change it to run the command again. |
env |
mapping of names to strings | none | Environment variables of the command; values are templates. |
cwd |
folder | the source folder | The working directory of the command, relative to the source folder. |
timeout |
duration | none | How long the command, or each worker request, may take. |
stderr |
fail, warn or ignore |
fail |
What output on stderr means. |
shell |
true or false |
true |
Run through /bin/sh -c (cmd.exe /d /s /c on Windows), or split the line and run the program directly. |
tool, mode, outputs, sources, version, env, cwd, timeout, stderr and shell are only valid with
run. The command fields are described in Command steps and workers.
needs, inputs and matchLink to this heading
- A step with
inputsreceives the source files that match them. A step withneedsreceives the files that come out of those steps, and sees the data they published (site data, folder data, collections). A step can have both. A step with neither is an error. matchselects among the entering files. It is matched against a file's current path, which changes when a permalink step moves files to their output paths (docs/guide.mdbecomes/guide/index.html).
group-byLink to this heading
file: one group per file path.dir: one group per folder.- Any other value is a Liquid template rendered for each file with
file(path,dir,name,ext) anddata(the file's data); files with the same result are a group.
A step that does not support grouping reports step '<name>' does not support 'group-by'.
enabledLink to this heading
enabled: false is a switch between two steps: the disabled step is removed, and the steps that need it need its
own needs.
steps:
pages:
inputs: "**"
uses: frontmatter
minify:
needs: pages
run: "npx html-minifier-terser"
mode: filter
match: "**/*.html"
enabled: false
write:
needs: minify
uses: write
With minify disabled, write needs pages.
enabled can also be a Liquid expression, written as in {% if %}. It is evaluated once, when the workflow file is
loaded, and sees:
| Name | Value |
|---|---|
os |
windows, linux, macos or other |
arch |
The processor architecture: x64, arm64, ... |
env |
The environment variables: env.CI. A missing one is nil; names are case insensitive on Windows. |
watch |
true for douze watch and douze serve, false for a build |
vars |
The variables, once the environment variables and the command line have set them |
vars:
og: true
steps:
og:
needs: pages
uses: social-image
enabled: "vars.og and env.CI"
with:
template: og.svg.liquid
output: "og{{ page.url }}.png"
check:
needs: og
uses: hover-typescript
enabled: "watch == false"
minify:
needs: check
run: "npx html-minifier-terser"
mode: filter
match: "**/*.html"
enabled: "os != 'windows'"
write:
needs: minify
uses: write
og runs in CI builds unless --var og=false turns it off, check only in builds, not while editing, and minify
everywhere but on Windows. --print-workflow prints the workflow with the expressions evaluated: a step that is not
enabled is not in it. In douze watch and douze serve, the expressions are evaluated again when the workflow file
changes.
| Error | Cause |
|---|---|
'enabled': invalid expression '<expression>': ... |
The expression does not parse. Filters are not supported. |
'enabled' must be true, false or a Liquid expression |
A list or a mapping. |
GlobsLink to this heading
Globs match virtual paths, which start at the source folder (docs/a.md is /docs/a.md; a leading / in a glob is
ignored). Matching is case sensitive.
| Syntax | Matches |
|---|---|
* |
Any characters within a folder. |
** |
Any characters across folders. docs/** also matches the folder itself. |
? |
One character, not /. |
{a,b} |
Alternatives, which can nest. |
[a-z], [abc] |
A character of the class. |
[!a-z] |
A character outside the class. |
\ |
Escapes the next character. |
! (leading) |
Excludes. In a list, the last matching glob decides. |
["docs/**", "!**/*.yml"] is every file of docs but the YAML files. An invalid glob is an error such as
invalid pattern '[a': unterminated character class; the other messages are empty pattern, unmatched '}',
trailing escape character and unterminated alternative.
DurationsLink to this heading
timeout is a positive number followed by a unit: 500ms, 30s, 5m, 1h. Anything else is an error:
invalid timeout '10'; use 30s, 5m or 1h.
Default workflowLink to this heading
Without steps, Douze runs this workflow for a site with _content, _data and _includes folders.
douze --print-workflow prints it with one line per step:
steps:
site-data:
inputs: "_data/**/*.{yml,yaml,json,xml}"
uses: data
with:
scope: site
folder-data:
inputs: "_content/**/*.{yml,yaml,json,xml}"
uses: data
with:
scope: folder
root: _content
pages:
inputs: ["_content/**", "!_content/**/*.{yml,yaml,json,xml}"]
needs: [site-data, folder-data]
uses: frontmatter
permalink:
needs: pages
uses: permalink
with:
root: _content
collections:
needs: permalink
uses: collect
paginate:
needs: [permalink, collections]
uses: paginate
render:
needs: paginate
uses: liquid
markdown:
needs: render
uses: markdown
layout:
needs: markdown
uses: layout
write:
needs: layout
uses: write
For a site whose content is the source folder (no _content) and without _data, there is no site-data step and
the data, includes and output folders and douze.yml are excluded from the pages:
steps:
folder-data:
inputs: ["**/*.{yml,yaml,json,xml}", "!douze.yml"]
uses: data
with:
scope: folder
pages:
inputs: ["**", "!**/*.{yml,yaml,json,xml}", "!douze.yml"]
needs: folder-data
uses: frontmatter
permalink:
needs: pages
uses: permalink
collections:
needs: permalink
uses: collect
paginate:
needs: [permalink, collections]
uses: paginate
render:
needs: paginate
uses: liquid
markdown:
needs: render
uses: markdown
layout:
needs: markdown
uses: layout
write:
needs: layout
uses: write
The output of --print-workflow is valid douze.yml: copy it into the file to start from the default workflow.
Fields with their default value are left out.
Validation errorsLink to this heading
Every error of the file is reported before the build stops with exit code 2, each with the position of the value it is about, or of the step's name for the errors about how steps fit together:
douze.yml(12,5): error: unknown field 'if' on step 'render'
douze.yml(14,3): error: step 'render' needs unknown step 'markdwn'; did you mean 'markdown'?
The errors of the file's shape are reported first; the errors of the graph (unknown steps, cycles, step options) once the shape is valid.
| Message | Cause |
|---|---|
a workflow file must be a mapping with 'site', 'vars', 'markdown' and 'steps' |
The file is a list or a scalar. |
duplicate key '<key>', keys must be strings |
Any mapping. |
unknown key '<key>' in 'site'; expected ... |
Also for markdown, markdown.aside, markdown.code, markdown.images, site.locales and its languages. |
'<key>' must be a folder inside the source folder |
A site folder with ... |
'parallelism' must be a positive integer |
|
'site.locales' needs 'default', the locale whose pages have no url prefix |
|
'default' must be a locale folder name, '<name>' is not a locale folder name |
Names with /, \, spaces, . or ... |
'dir' must be 'ltr' or 'rtl' |
|
unknown aside kind '<kind>'; expected ... |
A titles or icons key that is not in kinds. |
'kinds' must list at least one kind |
|
'quality' must be an integer from 1 to 100, 'loading' must be 'lazy' or 'eager', 'widths' must be a list of positive integers |
markdown.images. |
'vars' must be a mapping of names to values, unknown variable '<name>' ... |
See vars. |
'steps' must be a mapping of step names to steps |
|
invalid step name '<name>': use lowercase letters, digits and dashes |
|
step name '<name>' is longer than 64 characters |
|
'source' is a reserved step name |
|
step '<name>' needs 'uses' or 'run' |
|
step '<name>' cannot have both 'uses' and 'run' |
|
unknown field '<field>' on step '<name>' |
With a suggestion when a field is close. |
'<field>' must be <type> |
A field of the wrong type, such as 'needs' must be a string or a list of strings. |
'<field>' is only valid with 'run' |
A command field on a uses step. |
'enabled': invalid expression '<expression>': ... |
See enabled. |
unknown tool 'pagefnd' on step 'search'; Douze knows 'lightningcss' or 'pagefind' |
A tool that Douze does not know. |
'with' is only valid with 'uses' or with 'mode: worker' |
|
'outputs' is only valid with 'mode: batch' |
|
step '<name>' is defined twice |
|
step '<name>' needs unknown step '<need>' |
With a suggestion. |
step '<name>' has no 'needs' and no 'inputs', so nothing enters it |
|
steps form a cycle: layout -> markdown -> layout |
|
unknown built-in step '<uses>' |
With a suggestion. |
step '<name>' does not support 'group-by' |
|
unknown option '<option>' for step '<name>' |
A with key the built-in step does not declare. |
option '<option>' of step '<name>' must be <type> |
A with value of the wrong type. |
step '<name>' needs the option '<option>' |
A required with option is missing. |
A workflow without a write step builds with a warning:
no 'write' step: nothing will be written to the output folder.