GuideConfiguration
Editor setup
Set up an editor for Liquid, YAML and Markdown files of a Douze site.
A Douze site is plain files: Markdown, HTML, Liquid templates and YAML. Any editor works. This page has tips to get syntax highlighting, validation and previews that match how Douze reads those files, with VS Code as the example.
Extensions for VS CodeLink to this heading
| Extension | For |
|---|---|
Liquid (sissel.shopify-liquid) |
Highlighting and formatting of Liquid in .liquid, .html and .md files |
YAML (redhat.vscode-yaml) |
Syntax checks of douze.yml, front matter and data files |
Douze uses Fluid, which implements Shopify's Liquid: extensions made for
Shopify themes highlight it correctly. Douze's own tags (shortcodes, include_markdown, image, error) are
highlighted like any other tag. A Shopify extension may flag them, or Douze's filters, as unknown: that is a warning
of the extension, not of Douze.
File associationsLink to this heading
Layouts and includes can be .liquid or .html files, and output templates are named after their output
(feed.xml.liquid, llms.txt.liquid). If your editor does not recognize Liquid in some of them, associate the
extensions in .vscode/settings.json:
{
"files.associations": {
"*.liquid": "liquid",
"_includes/**/*.html": "liquid"
},
"emmet.includeLanguages": {
"liquid": "html"
}
}
emmet.includeLanguages keeps Emmet's HTML abbreviations in Liquid files.
douze.ymlLink to this heading
Douze does not publish a JSON schema for douze.yml, so editors do not complete its keys. Douze validates the file
itself, before every build, and reports every error with its position:
douze.yml(6,43): error: unknown field 'if' on step 'render'
Two habits help:
douze --print-workflowprints the workflow a build runs, the default steps included, in the format of the file. It is a starting point to copy from, and a quick way to check a change, since it fails on an invalid file.- The douze.yml reference and the built-in steps list every key and option.
With douze serve running, an invalid douze.yml prints its errors as soon as you save it, and the session waits for
the next change.
Markdown previewsLink to this heading
The Markdown preview of an editor renders CommonMark, not what Douze renders:
- Liquid tags and variables (
{% badge "New" %},{{ site.url }}) are shown as text. Douze runs Liquid before Markdown. - Containers (
:::tip), heading ids and the other extensions of themarkdownsection render differently, or not at all. - Links between
.mdfiles work in the preview, and Douze rewrites them to the URLs of the pages (links: true), so writing them that way keeps both working.
douze serve is the preview that matches the site: it rebuilds the page on save and reloads it in the browser.
FormattingLink to this heading
Formatters such as Prettier may reflow Liquid in .html and .md files, or change the spacing in tags. When a
formatter breaks a template, exclude the includes folder from it, or use a Liquid plugin for the formatter.