Skip to content

Latest commit

 

History

History
108 lines (83 loc) · 3.18 KB

README.md

File metadata and controls

108 lines (83 loc) · 3.18 KB
Raw

hakyll-nix-template

Hakyll + Nix template

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