dream2nix/docs/README.md

# About this Documentation

Dream2nix documentation is generated from markdown via 
[mkdocs](https://www.mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).

## Build

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

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

# Development shell

Or alternatively run a development environment with:

``` shellsession
nix develop .#website
```

Upon entering the devshell, it will change into
`./docs` and symlink a build of the [options reference](#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`:

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

## Options Reference

The reference documentation for [modules](./modules.md) 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.md`s. 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](https://python-markdown.github.io/) with various, optional extensions listed in `./docs/mkdocs.yml`.

This is different from the CommonMark dialect, as implemented by [markdown-it-py](https://pypi.org/project/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](#options-reference), but it's good
to be aware of them when writing longer prose.

[mkdocs-materials reference](https://squidfunk.github.io/mkdocs-material/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](https://github.com/nix-community/dream2nix/blob/main/.github/workflows/pages.yml)