nani.wtf/README.md

hakyll-nix-template

Hakyll + Nix template

Usage

1. Click the "Use this template" button and create your repository
2. Renaming
3. Rename all instances of hakyll-nix-template with the name of your project
4. Rename generator/hakyll-nix-template.cabal to reflect your project name
5. Cachix
6. Create a cachix cache for your project on https://app.cachix.org
7. Follow the cachix instructions to generate a signing keypair
8. Copy the signing keypair value to a new CACHIX_SIGNING_KEY secret on https://github.com///settings/secrets
9. Run nix-build to build the project and nix-shell to open the nix shell
10. 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
11. 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.
12. 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.
13. 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
  • nix-linter
  • nixpkgs-fmt
  • ormolu
  • shellcheck
• Encourages dev use of lorri
• Deployment through a GitHub Actions build with cachix and deploying to GitHub Pages via a gh-pages branch