1 files changed, 35 insertions, 0 deletions
diff --git a/hakyll-nix/Readme.org b/hakyll-nix/Readme.org
new file mode 100644
index 0000000..ae742f4
--- /dev/null
+++ b/hakyll-nix/Readme.org
@@ -0,0 +1,35 @@
+#+TITLE: nix-wrapper around hakyll
+
+This is a simple wrapper around hakyll, which will build hakyll sites
+with nix while attempting to minimise the hassle of constantly
+recompiling the ~site.hs~ script.
+
+* Components
+
+~default.nix~ contains a function that will take exactly one argument
+(a path to some directory containing a ~site.hs~ file), and will return
+a function that can be called with ~haskellPackages.callPackage~ to
+make a derivation.
+
+~build.nix~ containes a function that will build a hakyll site if given
+a suitable directory. However, consider decoupling the build logic
+from your site's content by putting your ~site.hs~ script into a
+seperate directory from the rest of your site, to stop nix from
+recompiling it each time you make a minor change to any other file.
+
+Called with default arguments, ~build.nix~ will built the hakyll
+example that ships with ~hakyll-init~, as found in ~./defaultsite~.
+
+* Considerations
+
+Usually, it is advisable to build haskell projects with ~stack~, but
+this can easily result in the ~site.hs~ script being compiled to a
+single binary over a gigabyte in size (and recompiled from scratch
+each time something changes). Instead, the version here will use
+the haskell packages contained in ~nixpkgs~ to minimise build times,
+since these are usually available as prebuilt substitutes.
+
+Also note that the built hakyll script is only needed to build the
+actual site itself, and not a runtime-dependency, i.e. it will not
+be connected to a garbage collection root by default and may be removed
+by ~nix-collect-garbage~.