[CI] Migrate to npm-managed local Hugo and standardise Makefile targets

CONTRIBUTING.md

@@ -80,18 +80,10 @@ Please contribute! Layer5 documentation uses Jekyll and GitHub Pages to host doc
 1. Open a pull request (in your web browser) against the repo.
 
 
-#### Tests
-Users can now test their code on their local machine against the CI checks implemented using `make run-tests`.
-
-To test code changes on your local machine, run the following command:
-```
-make run-tests
+#### Build Verification
+To verify the site builds correctly on your local machine, run:
 ```
-
-#### Building Docker image
-To build a Docker image of the project, please ensure you have `Docker` installed to be able to build the image. Now, run the following command to build the Docker image:
-```sh
-make docker
+make build
 ```
 
 ### UI Lint Rules

Makefile

@@ -18,28 +18,43 @@ include .github/build/Makefile.show-help.mk
 #----------------------------------------------------------------------------
 # Academy
 # ---------------------------------------------------------------------------
-.PHONY: setup build site clean check-go theme-update
+.PHONY: setup check-deps check-go build build-preview site serve clean theme-update
 
 ## ------------------------------------------------------------
 ----LOCAL_BUILDS: Show help for available targets
-	
+
 ## Local: Install site dependencies
 setup:
-	 npm i
+	npm i
+
+## Verify required commands and local dependencies are present.
+check-deps:
+	@echo "Checking if 'npm' and local 'hugo' binary are present..."
+	@command -v npm > /dev/null || { echo "Error: 'npm' not found. Please install Node.js and npm."; exit 1; }
+	@test -x node_modules/.bin/hugo || { echo "Error: Hugo binary not found in node_modules. Please run 'make setup' first."; exit 1; }
+	@echo "Dependencies check passed."
+
+## Build site for production (no drafts, no future, no expired content).
+build: check-deps check-go
+	npm run build:production
 
-## Local: Build site for local consumption
-build:
-	hugo build
+## Build site for preview (no drafts, no future, no expired content) with dynamically set baseURL.
+build-preview: check-deps check-go
+	npm run build:preview
 
 ## Local: Build and run site locally with draft and future content enabled.
-site: check-go
-	hugo server -D -F
-
+site: check-deps check-go
+	npm run dev:site
+
+## Local: Run site locally in serve mode (without file watching).
+serve: check-deps check-go
+	npm run dev:serve
+
 ## Empty build cache and run on your local machine.
-clean: 
-	hugo --cleanDestinationDir
-	make setup
-	make site
+clean:
+	npm run clean
+	$(MAKE) setup
+	$(MAKE) site
 
 ## ------------------------------------------------------------
 ----MAINTENANCE: Show help for available targets
@@ -50,6 +65,6 @@ check-go:
 	@echo "Go is installed."
 
 ## Update the academy-theme package to latest version
-theme-update:
+theme-update: check-deps check-go
 	echo "Updating to latest academy-theme..." && \
-	hugo mod get github.com/layer5io/academy-theme
+	npm run update:theme

README.md

@@ -50,17 +50,20 @@ Academies are modular, Git-native learning management systems (LMS), which can b
 - [Go](https://go.dev/dl/) ≥ 1.26
 - [Hugo Extended](https://gohugo.io/getting-started/installing/) ≥ 0.158 (required for `hugo.Sites` in offline search index; CI uses 0.158)
 
-2. **Fetch and tidy dependencies**
+2. **Fetch dependencies and install local Hugo**
 
 ```bash
-   go mod tidy
-   ```
+go mod tidy
+make setup
+```
 
 3. **Run the local Hugo server**
 
 ```bash
-   hugo server
-   ```
+make site
+```
+
+*(This uses the locally installed `hugo-extended` version to prevent version conflicts).*
 
 The local preview uses the academy-theme or any styling updates that you have made. When paired with a Remote Provider, academy content might be presented differently.
 

package.json

@@ -13,15 +13,18 @@
     "_build": "npm run _hugo-dev --",
     "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo",
     "_hugo": "hugo --cleanDestinationDir",
-    "_hugo-dev": "npm run _hugo -- -e dev -DFE",
-    "_local": "npx cross-env HUGO_MODULE_WORKSPACE=docsy.work",
-    "_serve": "npm run _hugo-dev -- --minify serve --renderToMemory",
+    "_hugo-dev": "hugo --cleanDestinationDir -e dev -DFE",
+    "_local": "cross-env HUGO_MODULE_WORKSPACE=docsy.work",
+    "_serve": "npm run _hugo-dev -- server --minify --renderToMemory",
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"",
     "build:production": "npm run _hugo -- --minify",
     "build": "npm run _build -- ",
     "check:links:all": "HTMLTEST_ARGS= npm run _check:links",
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public/* resources",
+    "dev:build": "npm run _hugo-dev --",
+    "dev:serve": "npm run _hugo-dev -- server --watch=false",
+    "dev:site": "npm run _hugo-dev -- server",
     "local": "npm run _local -- npm run",
     "make:public": "git init -b main public",
     "precheck:links:all": "npm run build",
@@ -32,7 +35,8 @@
     "test": "npm run check:links",
     "update:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest",
     "update:hugo": "npm install --save-dev --save-exact hugo-extended@latest",
-    "update:pkgs": "npx npm-check-updates -u"
+    "update:pkgs": "npx npm-check-updates -u",
+    "update:theme": "hugo mod get github.com/layer5io/academy-theme"
   },
   "devDependencies": {
     "autoprefixer": "^10.4.21",