ReferenceBuilt-in steps
check-code
Checks that code samples and generated files are well formed: YAML, JSON, XML, Liquid, and douze.yml against its schema.
The check-code step checks that code is well formed, with parsers built into Douze: the fenced code blocks of your
pages, so that a sample a reader copies is valid, and generated files such as feeds and JSON exports. A douze.yml
sample is also checked against the workflow schema. Files pass through unchanged.
| Shape | map (no group-by) |
Default match |
**/*.html |
| Default workflow | no |
What it doesLink to this heading
What the step checks depends on the file:
- An HTML page: its code fences, as the markdown step writes them (
<pre data-lang="yaml">). Put the step aftermarkdownand before highlight, which replaces the fences with highlighted markup. The code is checked as written: lines and columns in errors are those of the fence. - Any other file: its whole content, by the language of its extension:
/feed.xmlis checked as XML. Select these files withmatch, after layout for generated files. A file whose extension has no validator passes through unchecked.
| Language | Checks | Fence languages and extensions |
|---|---|---|
yaml |
every document of the stream, and no key defined twice in a mapping; tabs in indentation are errors | yaml, yml |
json |
one JSON value, no comments, no property defined twice | json, webmanifest |
jsonc |
the same, with comments and trailing commas | jsonc |
jsonl |
a JSON value on every line that is not blank (JSON Lines) | jsonl, ndjson |
xml |
well-formed XML; in a fence, several elements are allowed. A DTD is ignored and nothing is downloaded | xml, svg, xsl, xslt, rss, atom |
liquid |
the template parses, with Douze's tags and filters and the site's shortcodes | liquid |
douze.yml samplesLink to this heading
A YAML fence whose title is douze.yml (```yaml title="douze.yml"), and a YAML file named douze.yml, is also
checked as a Douze workflow, with the rules of douze build: unknown keys of site, markdown, vars and of a step,
invalid values, unknown uses, unknown or invalid with options, unknown tool. needs that name steps the sample
does not show are not errors, since a sample shows part of a workflow. A sample of steps without the steps: line
(every top-level key is a step with uses, run, needs or inputs) is checked as the content of steps.
Leaving a sample outLink to this heading
A sample that is wrong on purpose, or that uses a shortcode your site does not have, takes the nocheck word in its
meta:
```yaml nocheck
title: [unclosed
```
The highlighter ignores the word. ignore leaves whole pages or files out.
OptionsLink to this heading
| Option | Type | Default | Meaning |
|---|---|---|---|
languages |
string or list | every language | The validators that run: yaml, json, jsonc, jsonl, xml, liquid |
aliases |
mapping | none | More fence languages or extensions for a validator: { compose: yaml, plist: xml }. A built-in alias (svg) cannot change validator |
workflow |
string or list | douze.yml |
The fence titles and file names checked as a Douze workflow; [] for none. A title with folders (site/douze.yml) matches by its file name |
skip |
string | nocheck |
The meta word that leaves a fence out |
ignore |
glob or list of globs | none | Pages and files left out, by output path |
errors |
fail or warn |
fail |
warn reports the errors as warnings and the build succeeds |
CachingLink to this heading
The step checks a page again only when its content changes; an unchanged page is replayed from the cache. With
errors: warn, the warnings of a replayed page are reported again, so a build from the cache shows the same warnings
as a full build. Adding or changing a shortcode checks the Liquid samples again.
ErrorsLink to this heading
Each error names the page by its source file, the fence by its language and its number among the checked fences of the page, its first line, then the line and column in the fence:
error: check-code: /guide/assets/index.html: /_content/guide/assets.md: yaml fence 3 ('steps:'): line 4, column 5: mapping values are not allowed in this context
error: check-code: /guide/images/index.html: /_content/guide/images.md: yaml fence 2 ('markdown:'): line 3, column 5: unknown key 'widthz' in 'markdown.images'; expected 'widths', 'formats', 'quality', 'output' or 'loading'
error: check-code: /reference/liquid/index.html: /_content/reference/liquid.md: liquid fence 21 ('{% for p in collections.all | locale_pages %}'): line 1, column 7: Invalid 'for' tag
error: check-code: /feed.xml: /feed.xml (/_content/feed.xml.liquid): xml: line 12, column 3: The 'item' start tag on line 9 position 4 does not match the end tag of 'channel'.
Every error of a page is reported. Like any step, check-code stops at the first page that fails; --keep-going
checks every page and reports them all. Invalid options are errors of douze.yml:
douze.yml(20,3): error: unknown language 'toml' in option 'languages' of step 'check-code'; expected 'yaml', 'json', 'jsonc', 'jsonl', 'xml', 'liquid'
douze.yml(20,3): error: alias 'svg' of step 'check-code' is checked by 'xml' already
ExampleLink to this heading
The samples of the pages are checked before highlighting, and the feed and the JSON export after the layouts:
steps:
pages:
inputs: "_content/**"
uses: frontmatter
permalink:
needs: pages
uses: permalink
render:
needs: permalink
uses: liquid
markdown:
needs: render
uses: markdown
check-code:
needs: markdown
uses: check-code
with:
aliases:
compose: yaml
highlight:
needs: check-code
uses: highlight
layout:
needs: highlight
uses: layout
check-files:
needs: layout
uses: check-code
match: ["**/*.xml", "**/*.json"]
write:
needs: check-files
uses: write
Rules of your ownLink to this heading
check-code checks syntax. For rules beyond it (a CSS linter, an HTML validator, a spelling check), run the tool as a
command step on a branch of the workflow: a step that no other step needs. A non-zero exit code, or
output on stderr (stderr: fail, the default), fails the build with the tool's output. On a branch, the files the
command consumes do not replace the files that continue to write.
steps:
pages:
inputs: "_content/**"
uses: frontmatter
markdown:
needs: pages
uses: markdown
layout:
needs: markdown
uses: layout
lint-css:
needs: pages
match: "**/*.css"
run: "npx stylelint \"{{ inputs }}/**/*.css\""
validate-html:
needs: layout
match: "**/*.html"
run: "npx html-validate {{ inputs }}"
write:
needs: layout
uses: write
Both are batch steps (the default mode): one process checks every file. Their results are cached like other
steps, so an unchanged site does not run them again.