This step is critical for local development! Without the haskell.nix binary cache, Nix will attempt to build GHC from source, requiring 13GB+ disk space and hours of compilation.

📖 Follow the official setup guide: haskell.nix Binary Cache Configuration

This configures pre-built GHC packages that make builds fast and practical for local development.

For macOS users:

nix flake check --accept-flake-config    # Run tests

For Linux users, you can also use:

nix build .#checks.x86_64-linux.csp-test --accept-flake-config    # Run tests
nix flake check --accept-flake-config                             # Run tests (alternative)

Started off with a template and its accompanying tutorial from rpearce.

It uses Hakyll + Nix.

• Updated the Github Actions workflows to use actions/deploy-pages@v4 instead (and changed Pages deployment settings to allow this).
• Added actions/attest-build-provenance@v2 for SLSA attestations of the build.

• Read the tutorial to get started! https://robertwpearce.com/the-hakyll-nix-template-tutorial.html

• If you make changes to anything inside of ssg/, you'll need to clean the hakyll cache and rebuild. This is the preferred series of commands for rebuilding (with logs), cleaning the cache, and re-running the dev server:

  nix build --print-build-logs && \
    nix run . clean && \
    nix run . watch
  

• Build your site into the ./result/dist folder:

  λ nix build
  

• Start hakyll's dev server that reloads when changes are made:

  λ nix run . watch
  Listening on http://127.0.0.1:8000
  ...more logs
  

• Run any hakyll command through nix run .!

  λ nix run . clean
  Removing dist...
  Removing ssg/_cache...
  Removing ssg/_tmp...
  

• Start a development environment that

  • has your shell environment
  • has hakyll-site (for building/watching/cleaning hakyll projects)
  • has hakyll-init (for generating new projects)
  • can have anything else you put in the shell.buildInputs of the hakyllProject in flake.nix
  • is set up to run ghci with some defaults and the modules loaded so you can make your own changes and test them out in the ghci REPL

  λ nix develop
  
  [hakyll-nix]λ hakyll-site build
  ...
  Success
  
  [hakyll-nix]λ ghci
  ...
  [1 of 1] Compiling Main    ( ssg/src/Main.hs, interpreted )
  ...
  
  λ >
  

All of this is custmomizable, and here are some things that are already done for you:

• pandoc markdown customization to make it as close to GitHub's markdown style as possible
• slugger module is included that makes nice link URIs based on post titles
• RSS & Atom XML feed generation
• Sitemap generation
• Code syntax highlighting customization
• ...other reasonable defaults

Configure the dev server, cache & tmp directories, and more in ./ssg/src/Main.hs.

Deployment is set up through a GitHub Action with cachix, and it deploys to a GitHub Pages branch, gh-pages, when you merge code into your main branch.

Setup information can be found below in the "Cachix" section.

Note: If your main branch's name isn't main, ensure 'refs/heads/main' gets updated to 'refs/heads/my-main-branch' in ./github/workflows/main.yml.

If you don't have nix, follow the nix installation instructions.

Once you have nix installed, follow the instructions here to get access to flakes: https://nixos.wiki/wiki/Flakes.

The ./.github/workflows/main.yml file builds with help from cachix, so you'll need to generate a signing key to be able to do this.

1. Create a cache on cachix for your project
2. Follow cachix's instructions to generate a signing keypair
3. Copy the signing keypair value to a new CACHIX_SIGNING_KEY secret on https://github.com/settings/secrets