Click the "Use this template" button and create your repository
Renaming
Rename all instances of hakyll-nix-template with the name of your project
Rename generator/hakyll-nix-template.cabal to reflect your project name
Cachix
Create a cachix cache for your project on https://app.cachix.org
Follow the cachix instructions to generate a signing keypair
Copy the signing keypair value to a new CACHIX_SIGNING_KEY secret on https://github.com///settings/secrets
Run nix-build to build the project and nix-shell to open the nix shell
If you want to update niv and the other pinned dependencies, then in the nix-shell run niv init and then niv update and then exit to leave the nix shell
To start an environment for running hakyll commands like hakyll-site watch (the dev server) and hakyll-site build: cd generator && nix-shell. You'll then have access to the hakyll-site executable defined in generator/hakyll-nix-template.cabal. While you can do nix-shell in the root and then cd generator && hakyll-site watch, you get some more tools if you nix-shell from within the generator/ folder.
Once you're satisfied, create a branch, push your project up there, and check that the GitHub Actions successfully build. If so, you're good to merge your project with your main branch.
Once you have a successful build on your main branch, open https://github.com///settings and set the GitHub Pages branch to be the gh-pages branch

Features

tl;dr: nix-build will collect all your pinned dependencies, build your hakyll site, and output the built site in a result/ directory. If you set up the main GitHub Action with what it needs (your cachix cache, and your app needs a CACHIX_SIGNING_KEY secret), it will deploy your built site to a gh-pages branch.

Hakyll (see the generator folder)
- Haskell nix-shell environment inside the generator folder through which you can run hakyll-site watch and all other hakyll commands, including the ability to run ghci and load haskell modules for testing
- Ability to patch hakyll via hakyll.patch
- Ability to provide nixpkgs overrides for packages whose versions need to come from hackage
- RSS & Atom XML feed generation
- Sitemap generation
- Reasonable pandoc markdown customization to make it as close to GitHub's style as possible
- Slug.hs module that makes nice URIs
- Many other opinionated general website setup features that should be very helpful
Nix
- Pinned nixpkgs, niv, and pre-commit-hooks.nix
- nix-build will build your site into a result/ directory
- nix-shell in the root will give you a shell with the tools dependencies in ./nix/default.nix
- nix-shell in ./generator will give you a haskell shell with your hakyll-site available, as well as ghci
Dev linting via pre-commit-hooks.nix
Encourages dev use of lorri
Deployment through a GitHub Actions build with cachix and deploying to GitHub Pages via a gh-pages branch