docs: fix onboarding instructions

The onboarding instructions previously omitted some required changes to the build path. This commit adds the relevant instructions, with some minor refactoring of `flake.nix` to make the process smoother.
cjshearer · Jun 25, 2024 · 4d11600 · 4d11600
1 parent b7d226f
commit 4d11600
Show file tree

Hide file tree

Showing 5 changed files with 62 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ _Host your own resume on GitHub for free!_
 
 ## Quick Start
 
-This guide helps you quickly test the theme and deploy it to github pages. If, when finished, you decide to keep using it, we suggest continuing with the [Extended Setup](#extended-setup) to convert your fork into something more maintainable.
+This guide helps you quickly test the theme and deploy your resume to github pages. If you like it, we suggest continuing with the [Extended Setup](#extended-setup).
 
 ### 1. Fork this repository
 
@@ -29,9 +29,9 @@ Edit the resume at `(your repo) > exampleSite/content/_index.md` using the githu
 
 ## Extended Setup
 
-The fork you created in the [Quick Start](#quick-start) won't be easy to keep up-to-date. Follow this guide to convert your forked `exampleSite` into something more maintainable.
+The fork you created in the [Quick Start](#quick-start) contains a _copy_ of the theme, which won't be easy to update. Follow this guide to convert your forked hugo site into one which _imports_ the theme.
 
-### 5. Extract the Example Site and Supporting Files
+### 5. Remove Theme Source Code
 
 Clone your forked repository and modify it as follows:
 
@@ -40,29 +40,29 @@ Clone your forked repository and modify it as follows:
 
 ```diff
  $ tree -av --dirsfirst -L 1 --gitignore
- .
- ├── .git
- ├── .github
- ├── .vscode
--├── assets
-+├── exampleSite/* # move its files to the root dir
--├── layouts
- ├── .envrc
- ├── .gitignore
- ├── LICENSE
- ├── README.md
- ├── biome.json
- ├── flake.lock
- ├── flake.nix
--├── go.mod
--├── go.sum
--├── hugo.toml
--├── package.hugo.json
--├── postcss.config.js
--└── tailwind.config.js
+  .
+  ├── .git
+  ├── .github
+  ├── .vscode
+- ├── assets
++ ├── exampleSite/* # move its files to the root dir
+- ├── layouts
+  ├── .envrc
+  ├── .gitignore
+  ├── LICENSE
+  ├── README.md
+  ├── biome.json
+  ├── flake.lock
+  ├── flake.nix
+- ├── go.mod
+- ├── go.sum
+- ├── hugo.toml
+- ├── package.hugo.json
+- ├── postcss.config.js
+- └── tailwind.config.js
 ```
 
-### 6. Modify your Hugo Module
+### 6. Rename your Hugo Module and Import Theme
 
 Rename your module and remove the replacement directive to change `modern-hugo-resume` from a local to a remote dependency:
 
@@ -71,15 +71,30 @@ Rename your module and remove the replacement directive to change `modern-hugo-r
 - module github.com/cjshearer/modern-hugo-resume/exampleSite
 + module github.com/<your username>/<your repo>
 
-...
 - // We use this for local development. Remove it if you're
 - // extracting the exampleSite to your own repository.
 - replace github.com/cjshearer/modern-hugo-resume => ../
 ```
 
-### 7. Update Hash for Vendored Hugo Dependencies
+### 7. Update Build Path, Name, and Dependency Hash
+
+GitHub Actions is configured to build the site using Nix. Now that your site is built from the root directory (not `exampleSite`), you should update its build path and name.
+
+Nix also requires the expected hash of downloaded dependencies. Now that `modern-hugo-resume` is imported, you will need to update this hash. Follow the instructions above `outputHash` in [`flake.nix`](./flake.nix).
+
+See [`cjshearer.dev/flake.nix`](https://github.com/cjshearer/cjshearer.dev/blob/77b6e94990ca1f7168760a41ea3ee7e9b3745b17/flake.nix) for reference.
 
-Nix to builds the site in GitHub Actions, and it requires that the expected hash of downloaded dependencies be declared. Now that you have added `modern-hugo-resume` as an additional remote dependency, you will need to update this hash. See the instructions above `outputHash` in [`flake.nix`](./flake.nix).
+```diff
+# flake.nix
+- sourceRoot = "exampleSite";
++ sourceRoot = ".";
+...
+- pname = "modern-hugo-resume-exampleSite"
++ pname = "<your username>.github.io"
+...
+- outputHash = "sha256-someOldHash=
++ outputHash = "sha256-someNewHash=
+```
 
 ### 8. Commit and Push
 
@@ -93,27 +108,22 @@ git push
 
 ## Local Development
 
-### Requirements 
-Can be installed manually, or automatically with [nix](https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#the-determinate-nix-installer) by running `nix develop`:
+### Requirements
+
+These can be installed manually, or automatically with [nix](https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#the-determinate-nix-installer) by running `nix develop`:
 
 1. Install [`hugo`](https://gohugo.io/installation/) 1.27.0+extended.
 2. Install [`go`](https://go.dev/dl/) >= 1.22.3.
 3. Install `node` >= 20.2.0 with [nvm](https://github.com/nvm-sh/nvm).
 4. Install `pnpm` with `corepack enable`.
-5. Run `pnpm install`.
+5. Run `pnpm install` within `exampleSite`.
 
-### Common Nix Commands
+### Common Commands
 ```sh
+nix develop     # open a development environment, with all requirements satisfied
 nix build       # build the production site, exactly the same way it's done in CI
 nix flake check # run formatter/linter checks, exactly the same way it's done in CI
-nix develop     # open a development environment with requirements satisfied
-```
-
-#### Common pnpm Commands
 
-```sh
-cd exampleSite # <- don't forget this
-
-pnpm dev       # rebuild changes automatically 
-pnpm build     # create a production build
-```
+hugo server     # serve to localhost and rebuild changes automatically
+hugo --minify   # build static site for production
+```
diff --git a/exampleSite/package.hugo.json b/exampleSite/package.hugo.json
@@ -1,8 +1 @@
-{
-  "scripts": {
-    "build": "pnpm run hugo:build",
-    "dev": "pnpm run hugo:serve",
-    "hugo:build": "hugo --minify",
-    "hugo:serve": "hugo server"
-  }
-}
+{}
diff --git a/exampleSite/package.json b/exampleSite/package.json
@@ -18,11 +18,5 @@
     "postcss": "^8.4.38",
     "postcss-cli": "^11.0.0",
     "tailwindcss": "^3.4.4"
-  },
-  "scripts": {
-    "build": "pnpm run hugo:build",
-    "dev": "pnpm run hugo:serve",
-    "hugo:build": "hugo --minify",
-    "hugo:serve": "hugo server"
   }
 }
diff --git a/flake.nix b/flake.nix
@@ -19,6 +19,7 @@
         nodejs = pkgs.nodejs_22;
         pnpm = pkgs.pnpm;
         nativeBuildInputs = [ go hugo nodejs pnpm ];
+        sourceRoot = "exampleSite";
       in
       {
         checks = {
@@ -33,11 +34,12 @@
         };
 
         packages.default = pkgs.stdenv.mkDerivation (finalAttrs: {
-          pname = "modern-hugo-resume-exampleSite"; # remove once I get around to versioning this
-          name = finalAttrs.pname; # remove once I get around to versioning this
+          pname = "modern-hugo-resume-exampleSite";
+          # TODO: remove `name` once I get around to versioning this
+          name = finalAttrs.pname;
 
           src = ./.;
-          setSourceRoot = "sourceRoot=$(echo */exampleSite)";
+          setSourceRoot = "sourceRoot=$(echo *-source/${sourceRoot})";
 
           nativeBuildInputs = nativeBuildInputs ++ [ pnpm.configHook ];
 
@@ -65,14 +67,14 @@
                 outputHashAlgo = "sha256";
                 # To get a new hash:
                 # 1. Invalidate the current hash (change any character between "sha256-" and "=")
-                # 2. Run`nix build` (it will fail with a hash-mismatch and provide the actual hash)
-                # 3. Substitute the correct hash (`nix build` should now work)
+                # 2. Run `nix build` or push to GitHub (it will fail and provide the new hash)
+                # 3. Substitute the new hash (`nix build` should now work)
                 outputHash = "sha256-szsB5HwBznoZ1+qtj/yGgDQeUJxVdgtJ/4O1I25s4UE=";
               };
             in
             ''
               ln -s ${hugoVendor} _vendor
-              pnpm build -d $out
+              hugo --minify -d $out
             '';
 
           dontInstall = true;
@@ -86,7 +88,7 @@
           ];
 
           shellHook = self.checks.${system}.pre-commit-check.shellHook + ''
-            pushd exampleSite 
+            pushd ${sourceRoot}
             
             pnpm install
 

diff --git a/package.hugo.json b/package.hugo.json
@@ -1,5 +1,4 @@
 {
-  "author": "Cody Shearer",
   "comments": {
     "dependencies": {},
     "devDependencies": {
@@ -12,15 +11,12 @@
     }
   },
   "dependencies": {},
-  "description": "A resume website",
   "devDependencies": {
     "@fullhuman/postcss-purgecss": "^5.0.0",
     "@tailwindcss/typography": "^0.5.13",
     "autoprefixer": "^10.4.19",
     "postcss": "^8.4.38",
     "postcss-cli": "^11.0.0",
     "tailwindcss": "^3.4.4"
-  },
-  "name": "modern-hugo-resume",
-  "version": "0.0.1"
+  }
 }