docs: improve onboarding instructions

cjshearer · Jun 23, 2024 · 65c0563 · 65c0563
1 parent d5aff7e
commit 65c0563
Show file tree

Hide file tree

Showing 9 changed files with 124 additions and 103 deletions.
diff --git a/README.md b/README.md
@@ -1,22 +1,12 @@
 # modern-hugo-resume
 
-A responsive, minimal, print-friendly resume builder. Fork it as a standalone website, or use as a theme in a new or existing Hugo site. Powered by Hugo, Tailwind CSS, Nix, and GitHub Pages.
+A responsive, minimal, print-friendly resume builder. Powered by Hugo, Tailwind CSS, Nix, and GitHub Pages.
 
 _Host your own resume on GitHub for free!_
 
-## Requirements
-
-Can be installed manually, or with `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`.
-
 ## Quick Start
 
-Follow this guide to quickly deploy your resume to github pages.
+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.
 
 ### 1. Fork this repository
 
@@ -30,78 +20,87 @@ Under `(your repo) > Settings > Pages > Build and Deployment > Source`, select "
 
 Go to `(your repo) > Actions` and click "Enable workflows". These are disabled by default on forks, to prevent unintended workflow runs.
 
-### 4. Edit the Resume to Deploy the Site
+### 4. Deploy your Customized Resume
 
 Edit the resume at `(your repo) > exampleSite/content/_index.md` using the github editor. When you commit it, the resume site will automatically be built and deployed to `https://<your_username>.github.io`.
 
 > [!TIP]
 > You can skip editing the resume and trigger the build and deploy workflow manually by going to `Actions > ./github/workflows/deploy.yaml` and clicking "run workflow".
 
-## Minimal Setup
-
-Follow this guide if you want to handle deployment yourself. 
-
-> [!TIP] 
-> Feel free to adapt our nix-based `.github` workflows to your website. An example of this will be available on my [my website's repo](https://github.com/cjshearer/cjshearer.dev).   
+## Extended Setup
 
-### 1. Create and Clone Your New Repository 
+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 permanent.
 
-[Create a new repository](https://github.com/new), naming it `<your_username>.github.io` and cloning it locally.
+### 5. Extract the Example Site and Supporting Files
 
-### 2. Initialize a Hugo Module
+Clone your fork modify it as follows:
 
-Inside your local git repository, create a `go.mod` file with:
+1. Delete files and folders marked with a (-).
+2. Moving the files from `exampleSite` up a level with `mv exampleSite/* .` (ignore the error).
 
-```sh
-hugo mod init github.com/<your username>/<your repo name>
+```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
 ```
 
-### 3. Import this Theme
+### 6. Modify your Hugo Module
 
-Copy our `exampleSite/hugo.toml` to your repo's root directory, deleting the `replacements` line and editing the `baseURL`.
+Rename your module and remove the replacement directive:
 
 ```diff
-- baseURL = "https://cjshearer.github.io/modern-hugo-resume"
-+ baseURL = "https://<your_username>.github.io/<your_repo_name>"
-...
-[module]
-- replacements = "github.com/cjshearer/modern-hugo-resume -> ../.."
+// go.mod (originally from `exampleSite/go.mod`)
+- module github.com/cjshearer/modern-hugo-resume/exampleSite
++ module github.com/<your username>/<your repo>
 
-  [[module.imports]]
-  path = "github.com/cjshearer/modern-hugo-resume"
 ...
+- // 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 => ../
 ```
 
-### 4. Install Node Dependencies
+### 7. Add `modern-hugo-resume` as a Build Dependency
 
-Some of our dependencies (e.g. `tailwindcss`) are sourced from `npm`. Generate a `package.json` for these dependencies and install them with your preferred node package manager:
+Adding modern-hugo-resume to the list of Hugo modules in `flake.nix` is necessary to build the site in GitHub Actions. See the instructions in [`flake.nix`](./flake.nix), below `hugoModules`.
 
-```sh
-hugo mod npm pack
-pnpm install
-```
-
-### 5. Write your Resume
+### 8. Commit and Push
 
-Add your resume as a markdown file located in `content/_index.md`. See `exampleSite/content/_index.md` for an example. Be sure to include the frontmatter:
-```yaml
----
-title: Software Developer
-description: Full Stack Software Developer Resume
-faviconText: 💼
-layout: modern-hugo-resume
----
-```
-
-### 6. Run your Site
+Commit and push your changes to your main branch.
 
 ```sh
-hugo server
+git add .
+git commit -m "build: use hugo module"
+git push
 ```
 
 ## Local Development
 
-Development of this repository uses the following commands frequently.
+### 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`:
+
+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`.
 
 ### Common Nix Commands
 ```sh
@@ -117,4 +116,4 @@ cd exampleSite # <- don't forget this
 
 pnpm dev       # rebuild changes automatically 
 pnpm build     # create a production build
-```
+```
diff --git a/exampleSite/content/_index.md b/exampleSite/content/_index.md
@@ -123,7 +123,7 @@ June 2018 to August 2018
 
 August 2017 to May 2021
 
-- Graduated [_magna cum laude_](pdf/usc-diploma.pdf) with a mathematics minor
+- Graduated _magna cum laude_ with a mathematics minor
 - Achieved [Outstanding Senior Award](https://sc.edu/about/offices_and_divisions/leadership_and_service_center/awards_and_recognition/senior-awards/index.php) and the [Palmetto Fellows Scholarship](https://sc.edu/about/offices_and_divisions/financial_aid/scholarships/scholarships_for_sc_residents/palmetto_fellows/index.php)
 - Earned honors including President's List, Dean's List, and [Phi Beta Kappa](https://www.pbk.org/About)
 - Served as President and Treasurer of the Carolina Movement Club (_parkour!_)

diff --git a/exampleSite/go.mod b/exampleSite/go.mod
@@ -2,4 +2,11 @@ module github.com/cjshearer/modern-hugo-resume/exampleSite
 
 go 1.22.3
 
-require github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7 // indirect
+require (
+	github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7 // indirect
+	github.com/cjshearer/modern-hugo-resume v0.0.0-20240622205900-d5aff7eecfd0 // indirect
+)
+
+// 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 => ../
diff --git a/exampleSite/hugo.toml b/exampleSite/hugo.toml
@@ -20,15 +20,9 @@ wrapStandAloneImageWithinParagraph = false
   block = true
   title = true
 
-[module]
-replacements = "github.com/cjshearer/modern-hugo-resume -> ../.."
+[[module.imports]]
+path = "github.com/cjshearer/modern-hugo-resume"
 
-  [[module.imports]]
-  path = "github.com/cjshearer/modern-hugo-resume"
-
-  [[module.imports]]
-  path = "github.com/FortAwesome/Font-Awesome"
-
-  [[module.mounts]]
-  source = "hugo_stats.json"
-  target = "assets/watching/hugo_stats.json"
+[[module.mounts]]
+source = "hugo_stats.json"
+target = "assets/watching/hugo_stats.json"
diff --git a/exampleSite/package.hugo.json b/exampleSite/package.hugo.json
@@ -1,10 +1,8 @@
 {
-  "name": "exampleSite",
   "scripts": {
     "build": "pnpm run hugo:build",
     "dev": "pnpm run hugo:serve",
-    "hugo:build": "hugo -d build --minify",
+    "hugo:build": "hugo --minify",
     "hugo:serve": "hugo server"
-  },
-  "version": "0.1.0"
+  }
 }
diff --git a/exampleSite/package.json b/exampleSite/package.json
@@ -2,12 +2,12 @@
   "comments": {
     "dependencies": {},
     "devDependencies": {
-      "@fullhuman/postcss-purgecss": "../..",
-      "@tailwindcss/typography": "../..",
-      "autoprefixer": "../..",
-      "postcss": "../..",
-      "postcss-cli": "../..",
-      "tailwindcss": "../.."
+      "@fullhuman/postcss-purgecss": "github.com/cjshearer/modern-hugo-resume",
+      "@tailwindcss/typography": "github.com/cjshearer/modern-hugo-resume",
+      "autoprefixer": "github.com/cjshearer/modern-hugo-resume",
+      "postcss": "github.com/cjshearer/modern-hugo-resume",
+      "postcss-cli": "github.com/cjshearer/modern-hugo-resume",
+      "tailwindcss": "github.com/cjshearer/modern-hugo-resume"
     }
   },
   "dependencies": {},
@@ -19,12 +19,10 @@
     "postcss-cli": "^11.0.0",
     "tailwindcss": "^3.4.4"
   },
-  "name": "exampleSite",
   "scripts": {
     "build": "pnpm run hugo:build",
     "dev": "pnpm run hugo:serve",
     "hugo:build": "hugo --minify",
     "hugo:serve": "hugo server"
-  },
-  "version": "0.1.0"
+  }
 }
diff --git a/exampleSite/static/pdf/usc-diploma.pdf b/exampleSite/static/pdf/usc-diploma.pdf
diff --git a/flake.nix b/flake.nix
@@ -45,20 +45,45 @@
             hash = "sha256-RvE4R277Kam3s32XbGUIQTToG0cpbhpTaLEU5HsNZZ4=";
           };
 
-          fontAwesome = pkgs.fetchFromGitHub {
-            owner = "FortAwesome";
-            repo = "Font-Awesome";
-            rev = "6.5.2";
-            sha256 = "sha256-kUa/L/Krxb5v8SmtACCSC6CI3qTTOTr4Ss/FMRBlKuw=";
-          };
+          preBuild =
+            let
+              hugoModules = [
+                # If you're following the README's Recommended Setup guide and want to use this 
+                # flake for CI/CD, add an entry here for modern-hugo-resume (see my repo's flake 
+                # for an example https://github.com/cjshearer/cjshearer.dev/blob/main/flake.nix). 
+                # 
+                # For context:
+                # This is required because `nix build` is sandboxed by default, so remote 
+                # dependencies must be declared with their hashes. Please realize that this means a 
+                # hugo module's sha256 MUST be updated if you update a hugo module 
+                # (`hugo mod get -u`). To get a new hash:
+                # 1. Invalidate the current hash (change any character between "sha256-" and "=")
+                # 2. Run`nix build` (it will fail and provide new, corrected hash)
+                # 3. Provide the correct hash (`nix build` should now work)
+                {
+                  owner = "FortAwesome";
+                  repo = "Font-Awesome";
+                  rev = "6.5.2";
+                  sha256 = "sha256-kUa/L/Krxb5v8SmtACCSC6CI3qTTOTr4Ss/FMRBlKuw=";
+                }
+              ];
+            in
+            ''
+              go mod vendor
+              mv vendor _vendor
+              sed -i '/## explicit/d' _vendor/modules.txt
 
-          postBuild = ''
-            go mod vendor
-            mv vendor _vendor
-            sed -i '$d' _vendor/modules.txt
-            mkdir -p _vendor/github.com/FortAwesome/
-            ln -s $fontAwesome _vendor/github.com/FortAwesome/Font-Awesome
+              mkdir -p _vendor/github.com/{${(
+                pkgs.lib.concatMapStrings (module: "${module.owner},") hugoModules
+              )}}
 
+              ${(pkgs.lib.concatMapStrings (module:
+                "ln -s ${pkgs.fetchFromGitHub module} " +
+                "_vendor/github.com/${module.owner}/${module.repo}\n"
+              ) hugoModules)}
+            '';
+
+          postBuild = ''
             pnpm build -d $out
           '';
 

diff --git a/hugo.toml b/hugo.toml
@@ -10,13 +10,13 @@ tags = ["responsive", "minimal", "light", "dark", "dak mode"]
 homepage = "https://cjshearer.dev"
 name = "Cody Shearer"
 
-[module]
-  [module.hugoVersion]
-  extended = true
-  min = "0.116.3"
+[module.hugoVersion]
+extended = true
+min = "0.116.3"
 
-  [[module.imports]]
-  path = "github.com/FortAwesome/Font-Awesome"
-    [[module.imports.mounts]]
-    source = "svgs"
-    target = "assets/svgs"
+[[module.imports]]
+path = "github.com/FortAwesome/Font-Awesome"
+
+[[module.imports.mounts]]
+source = "svgs"
+target = "assets/svgs"