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

CONTRIBUTING.md

@@ -43,36 +43,8 @@ Make sure you have the following prerequisites installed on your operating syste
   go version
   ```
 
-- [Hugo](https://gohugo.io/installation/) 
 
 
-  - Install a recent release of the Hugo "extended" version. If you install from
-    the [Hugo release page](https://github.com/gohugoio/hugo/releases), make sure
-    you download the `extended` version, which supports SCSS.
-
-    To verify run:
-
-    ```
-    hugo version
-    ```
-
-  - Install `PostCSS` so that the site build can create the final CSS assets. You
-    can install it locally by running the following commands from the root
-    directory of your project:
-
-    ```sh
-    npm install --save-dev autoprefixer
-    npm install --save-dev postcss-cli
-    ```
-
-    Starting in
-    [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md),
-    you must also separately install `postcss`:
-
-    ```sh
-    npm install -D postcss
-    ```
-
 **Note:** If you're on a _Windows environment_ then it is highly recommended that you install [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) both for performance and ease of use.
 
 

Makefile

@@ -15,10 +15,13 @@
 include .github/build/Makefile.core.mk
 include .github/build/Makefile.show-help.mk
 
-## Install docs.layer5.io dependencies on your local machine.
-## See https://gohugo.io/categories/installation
-setup:
-	npm install
+# ---------------------------------------------------------------------------
+# Docs
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# MAINTENANCE: Show help for available targets
+# ---------------------------------------------------------------------------
 
 ## Verify required commands and local dependencies are present.
 check-deps:
@@ -27,20 +30,31 @@ check-deps:
 	@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."
 
-## Run docs.layer5.io on your local machine with draft and future content enabled.
-site: check-deps check-go
-	npm run dev:site
+## Validate 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."
 
-## Run docs.layer5.io on your local machine in serve mode (without file watching).
-serve: check-deps check-go
-	npm run dev:serve
+#----------------------------------------------------------------------------
+# LOCAL_BUILDS: Show help for available targets
+#----------------------------------------------------------------------------
+
+## Install docs.layer5.io dependencies on your local machine.
+## See https://gohugo.io/categories/installation
+setup:
+	npm install
 
 ## Build docs.layer5.io on your local machine.
-build: check-deps check-go
+build: check-go check-deps
 	npm run dev:build
 
+## Build docs.layer5.io for preview
+build-preview: check-go check-deps
+	npm run build:preview
+
 ## Build docs.layer5.io for production with optional base URL.
-build-production: check-deps
+build-production: check-go check-deps
 	set -e; \
 	if [ -n "$(BASE_URL)" ]; then \
 		base_url="$(BASE_URL)"; \
@@ -50,21 +64,32 @@ build-production: check-deps
 		npm run build:production -- --gc; \
 	fi
 
+## Build and run docs.layer5.io locally in serve mode.
+serve: check-go check-deps
+	npm run serve
+
+## Run docs.layer5.io on your local machine with draft and future content enabled.
+site: check-go check-deps
+	npm run dev:site
+
 ## Empty build cache and run docs.layer5.io on your local machine.
-clean: check-deps
-	npm run dev:clean
+clean:
+	npm run clean
+	$(MAKE) setup
 	$(MAKE) site
 
-## Verify Go is installed locally.
-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."
-
 ## Format code using Prettier
 format:
 	npm run format
 
+#----------------------------------------------------------------------------
+# DOCKER_BUILDS: Docker-based targets for CI/CD
+#----------------------------------------------------------------------------
+
+## Build and run docs website within a Docker container
+docker:
+	docker compose watch
+
 ## Install base OS dependencies needed in Docker-based docs builds.
 docker-install-base-deps:
 	apt-get update
@@ -135,19 +160,16 @@ docker-build-upstream:
 	HUGO_MODULE_REPLACEMENTS="github.com/$(UPSTREAM_MODULE_NAME) -> github.com/$(UPSTREAM_REPO) $(UPSTREAM_COMMIT)" \
 		hugo --ignoreVendorPaths "github.com/$(UPSTREAM_MODULE_NAME)" -d /out
 
-## Build and run docs website within a Docker container
-docker:
-	docker compose watch
-
 .PHONY: \
 	setup \
 	check-deps \
+	check-go \
 	build \
+	build-preview \
 	build-production \
-	site \
 	serve \
+	site \
 	clean \
-	check-go \
 	format \
 	docker \
 	docker-install-base-deps \

README.md

@@ -44,7 +44,7 @@ Explore tutorials and documentation by product in the https://docs.layer5.io web
 <details>
 
 <summary><h3>Build Docs with Golang</h3></summary>
-If your local development environment has a supported version (v1.21.0+) of Golang installed, next you'll need to install extended Hugo version as it has necessary SCSS/SASS support. Find all the Hugo packages here: <https://github.com/gohugoio/hugo/releases/tag/v0.120.4>
+If your local development environment has a supported version (v1.21.0+) of Golang installed, you are ready to proceed.
 
 Now to setup and run the site locally execute:
 

package.json

@@ -9,10 +9,12 @@
   "bugs": "https://github.com/layer5io/docs/issues",
   "spelling": "cSpell:ignore HTMLTEST precheck postbuild -",
   "scripts": {
-    "_build": "npm run _hugo-dev",
+    "dev:site": "npm run _hugo-dev -- server",
+    "dev:build": "npm run _hugo-dev --",
+    "_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",
+    "_hugo-dev": "hugo --cleanDestinationDir -e dev -DFE",
     "_serve": "npm run _hugo-dev -- --minify serve",
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${BASE_URL:-${DEPLOY_PRIME_URL:-/}}\"",
     "build:production": "npm run _hugo -- --minify --baseURL \"${BASE_URL:-/}\"",