Skip to content

Documentation

There is a separate devshell called docs which is provided for working with the docs locally.

It can be entered by running nix develop .#docs or cd'ing into the docs directory and allowing direnv to load it automatically.

devshells/docs.nix
1

The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the docs directory.

Serve locally

To serve the docs locally run mkdocs serve from within the docs directory:

1
2
3
4
5
6
7
8
❯ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - index.md
INFO    -  Documentation built in 0.26 seconds
INFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'
INFO    -  [16:22:36] Serving on http://127.0.0.1:8000/nixos-facter/

Versioning & Publication

Versioning of the docs is managed through mike.

It is responsible for managing the structure of the gh-pages branch in the repository.

Note

More information about versioning with MkDocs Material and mike can be found here.

Warning

Be sure to have fetched the latest changes for the gh-pages branch first. This is especially important if you are using mike locally to make manual changes to the published site.