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

.gitignore

@@ -14,5 +14,12 @@
 # Dependency directories (remove the comment below to include it)
 # vendor/
 
+# Node dependencies
+node_modules/
+
+# Hugo build output
+public/
+resources/
+
 # IDEs
 .vscode/*

CONTRIBUTING.md

@@ -54,10 +54,10 @@ Or you may configure your IDE, for example, Visual Studio Code to automatically
 Please contribute! Layer5 documentation uses Jekyll and GitHub Pages to host docs sites. Learn more about [Layer5's documentation framework](https://docs.google.com/document/d/17guuaxb0xsfutBCzyj2CT6OZiFnMu9w4PzoILXhRXSo/edit?usp=sharing). The process of contributing follows this flow:
 
 1. Create a fork, if you have not already, by following the steps described [here](./CONTRIBUTING-gitflow.md)
-1. In the local copy of your fork, navigate to the docs folder.
-`cd docs`
 1. Create and checkout a new branch to make changes within
 `git checkout -b <my-changes>`
+1. Install dependencies (including local Hugo).
+`make setup`
 1. Edit/add documentation.
 `vi <specific page>.md`
 1. Run site locally to preview changes.

Makefile

@@ -14,34 +14,48 @@
 
 include .github/build/Makefile.show-help.mk
 
-## Install docs.layer5.io dependencies on your local machine.
-## See https://gohugo.io/categories/installation
+.PHONY: setup check-deps check-go build site serve clean docker
+
+## ------------------------------------------------------------
+----LOCAL_BUILDS: Show help for available targets
+
+## Local: Install site dependencies
 setup:
 	npm install
 
-## Run docs.layer5.io on your local machine with draft and future content enabled.
-site: check-go
-	hugo server -D -F
-
-## Run docs.layer5.io on your local machine. Alternate method.
-site-fast:
-	gatsby develop
+## 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."
+
+## Local: Build and run site locally with draft and future content enabled.
+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
 
-## Build docs.layer5.io on your local machine.
-build:
-	hugo
+## Build site for production (no drafts, no future, no expired content).
+build: check-deps check-go
+	npm run build:production
 
-## Empty build cache and run docs.layer5.io on your local machine.
-clean: 
-	hugo --cleanDestinationDir
-	make site
+## Empty build cache and run site on your local machine.
+clean:
+	npm run clean
+	$(MAKE) site
 
-.PHONY: setup build site clean site-fast check-go
+## ------------------------------------------------------------
+----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."
 
+## Build and run site within a Docker container
 docker:
 	docker compose watch

README.md

@@ -1,6 +1,24 @@
 # layer5-repo-template
 This repository is used as the boilerplate for consistency across all Layer5 repos.
 
+## Quick Start (Local Preview)
+
+> **Note:** You do not need to install Hugo globally. The required `hugo-extended` binary is managed locally via npm when you run `make setup`.
+
+### Prerequisites
+- [Node.js & npm](https://nodejs.org/) (to manage the local Hugo Extended binary)
+- [Go](https://go.dev/dl/) ≥ 1.20 (if using Hugo Modules)
+
+### Setup & Run
+
+```bash
+# Install dependencies (including local Hugo)
+make setup
+
+# Start the local Hugo development server
+make site
+```
+
 <div>&nbsp;</div>
 
 ## Join the Layer5 community!

package.json

@@ -0,0 +1,22 @@
+{
+  "name": "layer5-repo-template",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Layer5 repository template – Hugo site boilerplate",
+  "scripts": {
+    "_hugo": "hugo --cleanDestinationDir",
+    "_hugo-dev": "hugo --cleanDestinationDir -e dev -DFE",
+    "_serve": "npm run _hugo-dev -- server --minify --renderToMemory",
+    "build:production": "npm run _hugo -- --minify",
+    "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",
+    "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"
+  },
+  "devDependencies": {
+    "hugo-extended": "0.147.6"
+  }
+}