Benjamin Prevor's Blog

using Hakyll + Nix template

Always a WIP

Quick tips

• 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
  

Features

• 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 )
  ...
  
  λ >
  

hakyll

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

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.

Setup

Nix & Flakes

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.

Cachix

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