GuideStart a new project
Develop and build
Serve a site with live reload while you write it, build it for production, and run builds in CI.
Douze has three commands that build a site: douze build builds it once, douze watch builds it again after every
change, and douze serve also serves it with live reload. They take the same options, and all three use the disk
cache, so they only run what changed since the previous build.
Serve while you writeLink to this heading
douze serve
douze serve builds the site, serves the output folder on http://localhost:8080/, and watches the source folder:
Build succeeded: 10 steps, 6 files written in 0.03 s, 37 units executed
Serving _site at http://localhost:8080/
Watching . for changes (Ctrl+C to stop)
_content/blog/first.md changed: 1 file written in 0.01 s, 10 units executed, 27 cached
--portpicks another port. When the port is taken,douze servestops withcannot listen on http://localhost:8080/: ... (choose another port with --port).- The server serves
index.htmlfor folder URLs (/blog/a/), redirects/blog/ato/blog/a/, and serves the site's404.html, when it has one, for missing files. Responses are sent withCache-Control: no-cache. - Ctrl+C stops the session.
Live reloadLink to this heading
The server adds a script to every HTML page it serves, before </body>. After each rebuild, it sends the pages the
URLs of the files the build wrote or deleted, and each page decides:
- it reloads when it is one of them, or when a script (
.js,.mjs) changed; - otherwise, it swaps in place the stylesheets that changed, without reloading, so the scroll position and the state of the page stay;
- it does nothing when neither applies: editing another page does not reload this one.
Pages also reload when they reconnect to a restarted server. The script is only added by the dev server: the files in the output folder are not changed.
The pages connect to the server with a WebSocket, at /__douze/socket: any number of pages can stay open without
slowing down the server's other requests. A proxy in front of douze serve, such as the one of a dev container or a
tunnel, must pass WebSockets through for live reload to work.
What a change rebuildsLink to this heading
A rebuild runs only what the change affects, like a build from the cache:
- Editing a page renders that page again, and the pages that list it when its title, tags or date changed.
- Editing an include or a layout renders the pages that use it.
- Editing a data file renders the pages that read what changed.
- Editing
douze.yml(or the file of--workflow) takes effect at the next rebuild. While it is invalid, its errors are printed and the session waits for the next change.
Changes are collected until none came for 150 ms, so saving several files, or switching branches, is one rebuild. The
output folder, the .douze folder and .git are not watched. A build that fails prints its errors, and the session
goes on. When the system loses change events, or reports a path the watcher cannot map to the source folder, the
next rebuild checks every source file instead of failing.
The cache stays open during the session. Another douze build of the same site meanwhile builds without it, with a
warning.
Skip slow steps while editingLink to this heading
enabled can be a Liquid expression that sees watch, true for douze watch and douze serve. A step that only
matters for the published site, such as a type check or a minifier, can stay out of the session:
steps:
minify:
needs: layout
run: "npx html-minifier-terser --collapse-whitespace"
mode: filter
match: "**/*.html"
enabled: "watch == false"
The steps that need minify then need layout while you edit. See
enabled.
Watch without a serverLink to this heading
douze watch
douze watch does what douze serve does, without the server: use it with another server, or when another tool
reads the output folder.
BuildLink to this heading
douze # the same as douze build
douze build -s site -o public
douze build is the default command. It builds the site once and prints a summary. The main options:
| Option | Meaning |
|---|---|
-s, --source <dir> |
The source folder (default: the current folder) |
-o, --output <dir> |
The output folder, relative to the current folder (default: _site) |
-w, --workflow <file> |
Another workflow file than douze.yml |
-p, --parallelism <n> |
The maximum number of units that run at once (default: the processor count) |
--keep-going |
Report every error of a failing step instead of stopping it |
--fail-fast |
Stop the whole build on the first error |
--no-cache |
Build without reading or writing the cache |
--plain |
One line per step instead of the live view |
-q, --quiet / -v, --verbose |
Errors only / one line per file and stack traces |
The command line reference lists every option.
The output folderLink to this heading
The output folder is _site in the current folder by default. -o sets another one, relative to the current folder;
site.output in douze.yml sets one relative to the source folder, and -o wins over it.
Douze never empties the output folder. Once a build succeeds, it deletes the files that previous builds wrote and this one did not: the pages of deleted or renamed sources, the pages a pagination no longer has, and the folders they leave empty. It keeps:
- the files that something else changed since Douze wrote them;
- the files that Douze did not write, such as the ones a command wrote directly into the output folder;
- everything, when the build fails or runs with
--no-cache, which has no record of the previous builds.
To start from an empty folder, delete it before the build.
Errors and exit codesLink to this heading
Each error names the step, the file and, when known, the position:
error: render: /blog/first/index.md(3,1): '{% endif %}' was expected
By default, a failing step stops, the steps that need it are skipped, and the independent steps finish. --keep-going
lets the failing step process its other files and report every error; --fail-fast stops everything at once.
| Exit code | Meaning |
|---|---|
0 |
The build succeeded |
1 |
The build has errors, or a requirement of a step is missing (see douze doctor) |
2 |
Invalid command line or workflow file |
130 |
The build was cancelled with Ctrl+C |
douze watch and douze serve exit with 0 when they are stopped with Ctrl+C, and with 2 when the workflow is
invalid at start or the port is taken.
Build in CILink to this heading
In CI, Douze prints one line per step instead of the live view: it does when CI is set (to anything but false or
0), when the output is redirected, or with --plain. A GitHub Actions job:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install douze
run: |
curl -fsSL https://raw.githubusercontent.com/sebastienros/douze/main/install.sh | sh -s -- --preview
echo "$HOME/.douze/bin" >> "$GITHUB_PATH"
- uses: actions/cache@v4
with:
path: .douze
key: douze-${{ github.sha }}
restore-keys: douze-
- run: douze build
- Caching the
.douzefolder between runs makes CI builds incremental, and keeps the tools that steps download. Without it, every CI build is a full build, which is correct, only slower. douze doctorchecks what the steps need (libvips, tools, commands) without building, and exits with1when something is missing.douze tools installdownloads the tools of the workflow ahead of time, for a cached or offline build.
See Deploy to GitHub Pages and Build your site with Docker.