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

Makefile

@@ -18,27 +18,42 @@ include .github/build/Makefile.show-help.mk
 #----------------------------------------------------------------------------
 # Academy
 # ---------------------------------------------------------------------------
-## Install site dependencies
+
+## ------------------------------------------------------------
+----LOCAL_BUILDS: Show help for available targets
+
+## Local: Install site dependencies
 setup:
-	npm install
+	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
+
+## Build site for preview with custom base URL.
+build-preview: check-deps check-go
+	npm run build:preview
 
-## Build and run site locally with draft and future content enabled.
-site: check-go
-	hugo server -D -F
-
-## Build site for local consumption
-build:
-	hugo build
+## Local: Build and run site locally with draft and future content enabled.
+site: check-deps check-go
+	npm run dev:site
 
-## Build site for local consumption
-build-preview:
-	hugo --baseURL=$(BASEURL)
+## 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
 
 ## Fix Markdown linting issues
 lint-fix:
@@ -54,14 +69,15 @@ lint-fix:
 ## ------------------------------------------------------------
 ----MAINTENANCE: Show help for available targets
 
+## Check if Go is installed
 check-go:
 	@echo "Checking if Go is installed..."
 	@command -v go > /dev/null || (echo "Go is not installed. Please install it before proceeding."; exit 1)
 	@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
 
-.PHONY: setup build site clean site-fast check-go theme-update
+.PHONY: setup check-deps check-go build build-preview site serve clean lint-fix theme-update

README.md

@@ -44,7 +44,7 @@ Once imported, the individual Exoscale icons will be available in the Designer's
 
 Before you begin, ensure you have:
 
-- [**Hugo**](https://gohugo.io/getting-started/installing/) (extended version, recommended v0.147.9 or later)
+- [**Node.js & npm**](https://nodejs.org/) (to manage the local Hugo Extended binary)
 - [**Go**](https://go.dev/doc/install) (v1.12 or later)
 
 ## Getting Started
@@ -56,10 +56,25 @@ Before you begin, ensure you have:
    cd exoscale-academy
    ```
 
-2. **(Optional: If contributing from a fork)**
+2. **Fetch dependencies and install local Hugo**
+
+   ```bash
+   go mod tidy
+   make setup
+   ```
+
+3. **Run the local Hugo server**
+
+   ```bash
+   make site
+   ```
+
+   *(This uses the locally installed `hugo-extended` version to prevent version conflicts).*
+
+4. **(Optional: If contributing from a fork)**
    - Edit `go.mod` and update the module path to match your fork. Save and commit.
 
-3. **Organization UID**
+5. **Organization UID**
    - All Exoscale Academy content is namespaced under its Organization ID:
 
      ```
@@ -225,7 +240,7 @@ Embed videos in a visually distinct `card` using:
 To preview your content locally, run:
 
 ```bash
-hugo server
+make site
 ```
 
 - Open the local URL displayed in your terminal browser.

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=exoscale-academy.work",
+    "_hugo-dev": "hugo --cleanDestinationDir -e dev -DFE",
+    "_local": "cross-env HUGO_MODULE_WORKSPACE=exoscale-academy.work",
     "_serve": "npm run _hugo-dev -- --minify serve --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.27",