From 87630118d84b70ee7492c9209813d8d4361256f4 Mon Sep 17 00:00:00 2001
From: Youwen Wu <youwenw@gmail.com>
Date: Thu, 31 Oct 2024 22:51:28 -0700
Subject: [PATCH] docs: update readme with new instructions

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 61 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index a56b413..3ec1812 100644
--- a/README.md
+++ b/README.md
@@ -7,30 +7,77 @@ powered by [hakyll](https://jaspervdj.be/hakyll/) and
 This repo is merely the source code, the actual site is hosted at
 [blog.youwen.dev](https://blog.youwen.dev).
 
-To build locally, install `nix` and enable flakes.
+To build locally, install `nix` and enable flakes. Additionally, install the
+`direnv` tool so that the provided binary utilities can be hooked into your
+shell. It is also possible to perform the following steps without `direnv` if
+you know what you are doing.
+
+Allow the `.envrc`:
 
 ```sh
-nix build
-
-nix run . watch
+direnv allow
 ```
 
-This starts a hot reload server at `localhost:8000`.
+Wait for the build to finish. Now, you will have the `rollup` and `hakyll-site`
+binaries in your PATH.
+
+We need to compile the site source code first, and then inject the bundled CSS
+and JS using `rollup`. This is done automatically by `nix build`, which is used
+for GitHub Pages deployment, but it is inconvenient for local development.
+Here's how to do it locally.
+
+First, we need to build the site. Run
 
 ```sh
-nix run . build
+hakyll-site build
+
+# sometimes, we need to ignore the cache if things aren't working
+hakyll-site rebuild
+
+# can also use `watch` for convenient development
+hakyll-site watch
+# starts dev server at localhost:8000
 ```
 
-This builds a local production version.
+This will create `./dist`, containing the static assets. However, the required
+CSS and JS is not in there yet! That is built by `rollup`, since we are using
+`tailwindcss` and `postcss` and some JS minifying tools.
 
-If any updates are made to the JavaScript or CSS, you will need to run
+First, we need the `node_modules`. We don't provide a `package-lock.json` since
+we don't use `npm` to manage node modules. Therefore, we need to obtain the
+`node_modules` used by the project.
+
+In the directory, there is a `node_modules` symlink to
+`result/lib/node_modules`. If we build the `nodeDeps` package, the
+`node_modules` will be made available at this path. So, run the following:
 
 ```sh
-pnpm install # only the first time
-
-pnpm build
+nix build .#nodeDeps
 ```
 
-This is because I still haven't figured out how to integrate the `rollup` build
-pipeline with `nix`. Since the CSS and JS are minimal, I just do it manually for
-now.
+This will install the node modules in the Nix store and create the `result`
+symlink. Keep in mind that if this `result` symlink is ever overwritten, you
+need to re-run the above command or else node_modules will not be accessible.
+
+Finally, run the following to generate the bundled CSS and JS files.
+
+```
+rollup -c
+```
+
+You have to re-run this whenever you change the CSS and JS files in `src/`.
+
+Keep in mind that if `hakyll-site` ever overwrites `dist/out`, you will also
+have to re-run this command.
+
+<!--```sh-->
+<!--nix build-->
+<!---->
+<!--nix run . watch-->
+<!--```-->
+<!---->
+<!--This starts a hot reload server at `localhost:8000`.-->
+<!---->
+<!--```sh-->
+<!--nix run . build-->
+<!--```-->