dream2nix/docs

About this Documentation

Dream2nix documentation is generated from markdown via mkdocs and mkdocs-material.

Build

You can build and server it locally with, i.e.:

nix build .#website
python3 -m http.server -d ./result

Development shell

Or alternatively run a development environment with:

nix develop .#website

Upon entering the devshell, it will change into ./docs and symlink a build of the options reference into ./docs/src/reference.

Normal builds will always use an up-to-date options reference, but during development you need to update this symlink yourself and remove it after use.

i.e. from inside the shell in ./docs:

# update
ln -sfT $(nix build --print-out-paths --no-link .#optionsReference) ./src/reference
# remove
rm ./src/reference

Options Reference

The reference documentation for modules is auto-generated via a custom hook in docs/hooks/render_options.py and a derivation in .#optionsReference.

The derivation includes, for each module, an options.json file as generated by nix via pkgs.nixosOptionsDoc as well as a README.md file, copied from the modules source directory. The existence of such a README.md is used as an indicator on whether to include a module in the reference documentation.

The hook runs whenever mkdocs renders one of the README.mds. Each of them gets concatenated with header and options reference, after the latter are run through jinja templates in ./docs/theme.

Notes on Markdown

Mkdocs uses a markdown dialect from Python-Markdown with various, optional extensions listed in ./docs/mkdocs.yml.

This is different from the CommonMark dialect, as implemented by markdown-it-py and used in NixOS official documentation.

The differences between both don't seem to be too relevant for the markdown features used in our options reference, but it's good to be aware of them when writing longer prose.

mkdocs-materials reference provides a good overview on useful extensions.

CI

The documentation is published on GitHub pages via a GitHub action, defined in .github/workflows/pages.yml