GuideHelp
Contribute to Douze
Build and test Douze, check the native AOT build, follow the repository conventions and work on the documentation.
Douze is developed on GitHub at sebastienros/douze. Issues and pull requests are welcome. This page explains how to build and test Douze, how to check the native AOT build, and the conventions the code follows.
Douze has no public release yet. Breaking changes are fine anywhere (APIs, configuration, front matter conventions, folder layout, command line options): prefer the cleanest design, without compatibility shims, obsolete members or migration code.
Repository layoutLink to this heading
| Folder | Contains |
|---|---|
Douze/ |
The douze tool: command line, workflow engine, steps, Liquid, Markdown, highlighting, images |
Douze.Tests/ |
The tests (xUnit v3) and their fixtures |
Douze.Tests.FakeTool/ |
A small program the command step tests run |
Sample/ |
A sample site that exercises most features |
bench/ |
Benchmarks of large sites and image processing (Benchmarks) |
docs/ |
This documentation site, built by Douze, and design documents |
scripts/ |
Maintenance scripts: the TextMate bundle, Sample output comparison, install script tests |
install.sh, install.ps1 |
The install scripts (Installation) |
Build and testLink to this heading
Install the .NET SDK that global.json pins (rollForward: latestFeature, prereleases allowed), then, at the root of
the repository:
dotnet build
dotnet test
Tests use xUnit v3 on Microsoft.Testing.Platform, which global.json opts into. The build treats warnings as errors
and enforces the code style (Common.props).
Build the sample site with the working tree's Douze:
dotnet run --project Douze -- -s Sample -o site-out
scripts/compare-sample.sh [base-ref] builds the sample with the Douze of another ref (default main) and with the
working tree, and diffs the two outputs: run it when a change should not change the output.
Check the native AOT buildLink to this heading
Douze ships as a native AOT dotnet tool, and continuous integration smoke tests the AOT build of every pull request.
Publish it and build the sample with it:
dotnet publish Douze -c Release -o tool-out
./tool-out/douze -s Sample -o site-out
Anything based on reflection must keep working under AOT. For instance the json Liquid filter serializes through the
source-generated context in Douze/Liquid/DouzeJsonContext.cs: a new type that reaches it is added there.
ConventionsLink to this heading
- Deterministic builds. Documents are processed in parallel, so anything collected across documents is sorted before it is exposed. Two builds of the same sources produce the same output.
- Collection order. Items of
collections.allandcollections.<tag>are sorted by date ascending, using front matterdatewhen it is defined, orpage.date(the file date) otherwise, then by source path (ordinal), as Eleventy does. - Pagination.
pagination.pages,page.nextand the other pagination links only link pages generated from the same template. - Dependencies. Package versions are managed centrally in
Directory.Packages.props, shared MSBuild properties live inCommon.props. Keep dependencies on their latest stable versions. - Fluid previews. Fluid comes from the 3.0 previews of the Feedz feed, declared in
NuGet.configwith package source mapping so that onlyFluid.*packages come from it. Update to the latest preview when you touch Fluid.
AGENTS.md holds the same guidance for AI coding agents; CLAUDE.md imports it. Record new guidance in AGENTS.md.
Continuous integration and releasesLink to this heading
| Workflow | Runs on | Does |
|---|---|---|
pr.yml |
pull requests to main |
tests, builds the documentation site on Linux, macOS and Windows (and checks it on Linux: lint, links, Playwright), packs the native AOT tool for Linux x64, macOS arm64 and Windows x64, smoke tests it and the install scripts |
docs.yml |
pushes to main that change docs/ or Douze/ |
builds the documentation site and deploys it to GitHub Pages |
build.yml |
pushes to main |
tests, then publishes framework dependent preview packages to Feedz |
publish.yml |
v* tags |
publishes the native AOT tool packages of each platform, and a CoreCLR fallback, to NuGet |
Publishing to NuGet uses trusted publishing through the release environment: there is no NuGet API key secret.
Work on the documentationLink to this heading
The documentation site is built by Douze itself, from docs/. docs/README.md has the writing rules. Serve it with
live reload, or build it to docs/_site:
douze serve -s docs # http://localhost:8080/douze/
douze -s docs
- Match the voice of the repository README: plain, precise and short, sentence case headings, no em dashes.
- Take every option, default and message from the code in
Douze/. When the README and the code disagree, the code wins. - Build every example a reader can run with the current
mainbefore publishing it. - Pages are rendered as Liquid before Markdown: a page that shows Liquid outside code fences sets
liquid: falsein its front matter, or wraps it inraw. - Link to other pages with relative links to their
.mdfile (guide/collections.md).
AGENTS.md requires a change to a feature to update the documentation in the same pull request.
Update the bundled grammars and themesLink to this heading
The highlight step bundles the TextMate grammars of tm-grammars and the themes of tm-themes in
Douze/Highlighting/textmate.zip. scripts/update-textmate.cs writes it, at the versions and integrities pinned in the
script:
dotnet run scripts/update-textmate.cs