nani.wtf/README.md

177 lines
5.0 KiB
Markdown

# hakyll-nix-template
[Hakyll](https://jaspervdj.be/hakyll/) + [Nix](https://nixos.org) template
[![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org)
## Features
### nix flakes
* Build your site into the `./result/dist` folder:
```sh
λ nix build
```
* Start hakyll's dev server that reloads when changes are made:
```sh
λ nix run . watch
Listening on http://127.0.0.1:8000
...more logs
```
* Run any hakyll command through `nix run .`!
```sh
λ 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 `buildInputs` of the `devShell` in
`flake.nix`; for example: `haskell-language-server`, `hlint`, and `ormolu`
* 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
```sh
λ nix develop
[hakyll]λ hakyll-site build
...
Success
[hakyll]λ ghci
...
[1 of 2] Compiling Slug ( ssg/src/Slug.hs, interpreted )
[2 of 2] Compiling Main ( ssg/src/Main.hs, interpreted )
...
λ > :type toSlug
toSlug :: T.Text -> T.Text
λ > import Data.Text (pack)
λ > toSlug (pack "What If I Told You...")
"what-if-i-told-you"
```
* Easily unbreak hakyll's nixpkgs distribution or change hakyll's compile flags
via the `./haskell-overlay.nix` and `hakyll.patch` files
### hakyll
All of this is custmomizable, and here are some things that are already done for
you:
* [pandoc](https://github.com/jgm/pandoc/) markdown customization to make it as
close to GitHub's markdown style as possible
* `Slug.hs` module 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](https://github.com/features/actions) with [cachix](https://cachix.org),
and it deploys to a [GitHub Pages](https://pages.github.com/) 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](https://nixos.org) _and are not running macOS_, follow
[the nix installation instructions](https://nixos.org/download.html).
At the time of writing, the macOS installation is in a weird place. You should
use this:
```sh
λ sh <(curl https://abathur-nix-install-tests.cachix.org/serve/yihf8zbs0jwph2rs9qfh80dnilijxdi2/install) --tarball-url-prefix https://abathur-nix-install-tests.cachix.org/serve
```
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](https://app.cachix.org), so you'll to generate a signing key to be able
to do this.
1. Create a cache on cachix for your project
1. Follow cachix's instructions to generate a signing keypair
1. Copy the signing keypair value to a new `CACHIX_SIGNING_KEY` secret on
https://github.com/settings/secrets
## Enable Content-Addressible Derivation (experimental)
Given you have your nix conf `experimental-features` set to something like
```
experimental-features = "nix-command flakes ca-derivations ca-references"
```
Uncomment the `__contentAddressed = true;` line in `haskell-ovelray.nix`, and
then run
```sh
λ nix build --experimental-features "ca-derivations flakes nix-command"
```
## Alternatives to the haskell overlay
### Overriding `legacyPackages`' haskell compiler packages
```nix
pkgs = nixpkgs.legacyPackages.${system};
myHaskellPackages = pkgs.haskell.packages.${haskellCompiler}.override {
overrides = hpFinal: hpPrev:
let
hakyll-src = hpPrev.callHackage "hakyll" "4.14.0.0" {};
pandoc-src = hpPrev.callHackage "pandoc" "2.11.4" {};
in {
hakyll = pipe hakyll-src [
doJailbreak
dontCheck
(withPatch ./hakyll.patch)
(withFlags [ "-f" "watchServer" "-f" "previewServer" ])
];
pandoc = pipe pandoc-src [
doJailbreak
dontCheck
];
};
};
```
## Pulling `hakyll-src` from GitHub
`hakyll-src`, used in the `haskell-overlay.nix` and in the prior example,
doesn't have to come from hackage; it could come from what your pinned nixpkgs
version has via `hakyll-src = hpPrev.hakyll`, or it could come from the hakyll
repo pinned as a nix flake input:
```nix
hakyll-src = {
url = "github:jaspervdj/hakyll/v4.14.0.0";
flake = false;
};
```
...and then:
```nix
hakyll-src = hpPrev.callCabal2nix "hakyll" hakyll-src {};
```