From 2fd90d887d47be8554262a73562e90c1486a4264 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Wed, 10 Jun 2026 11:47:48 +0000 Subject: [PATCH 1/3] [CI] Migrate to npm-managed local Hugo and standardise Makefile targets Signed-off-by: Heby T Paul --- CONTRIBUTING.md | 30 +----------------------------- Makefile | 20 +++++++++++++------- README.md | 4 ++-- package.json | 3 +++ 4 files changed, 19 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f743db3b4a..8bb224d395f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,35 +43,7 @@ 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:** The extended Hugo version and PostCSS are automatically managed via npm when you run `make setup`, so you do not need to install them globally. **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. diff --git a/Makefile b/Makefile index 05a333703ef..636f874df39 100644 --- a/Makefile +++ b/Makefile @@ -20,22 +20,28 @@ setup: npm install ## Run docs.layer5.io on your local machine with draft and future content enabled. -site: check-go - hugo server -D -F +site: check-deps check-go + npm run dev:site ## Build docs.layer5.io on your local machine. -build: - hugo +build: check-deps check-go + npm run dev:build docs-build-production: npm run build:production ## Empty build cache and run docs.layer5.io on your local machine. -clean: - hugo --cleanDestinationDir +clean: check-deps check-go + npm run dev:clean make site -.PHONY: setup build site clean check-go docker +.PHONY: setup build site clean check-deps check-go docker + +check-deps: + @echo "Checking dependencies..." + @command -v npm > /dev/null || (echo "npm is not installed. Please install it before proceeding."; exit 1) + @if [ ! -d "node_modules" ]; then echo "Dependencies not installed. Please run 'make setup' first."; exit 1; fi + @echo "Dependencies are installed." check-go: @echo "Checking if Go is installed..." diff --git a/README.md b/README.md index ee16b7c50a6..2de94885493 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,11 @@ Explore tutorials and documentation by product in the https://docs.layer5.io web

Build Docs with Golang

 -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: +If your local development environment has a supported version (v1.21.0+) of Golang installed, you are ready to proceed. The extended Hugo version (which has necessary SCSS/SASS support) is automatically managed by npm, so you do not need to install it globally. Now to setup and run the site locally execute: -1. `make setup` +1. `make setup` (This installs local dependencies, including Hugo) 2. `make site` 3. visit http://localhost:1313 diff --git a/package.json b/package.json index 42c0c0f47a2..1057464929c 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,9 @@ "bugs": "https://github.com/layer5io/docs/issues", "spelling": "cSpell:ignore HTMLTEST precheck postbuild -", "scripts": { + "dev:site": "hugo server -D -F", + "dev:build": "hugo", + "dev:clean": "hugo --cleanDestinationDir", "_build": "npm run _hugo-dev", "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo", "_hugo": "hugo --cleanDestinationDir", From 472d956ebafe112d6303b9667c12fb7283951a03 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Wed, 10 Jun 2026 12:58:04 +0000 Subject: [PATCH 2/3] chore: optimize clean target to prevent double-build Signed-off-by: Heby T Paul --- Makefile | 2 +- package.json | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 636f874df39..a76f7aee958 100644 --- a/Makefile +++ b/Makefile @@ -32,7 +32,7 @@ docs-build-production: ## Empty build cache and run docs.layer5.io on your local machine. clean: check-deps check-go - npm run dev:clean + npm run clean make site .PHONY: setup build site clean check-deps check-go docker diff --git a/package.json b/package.json index 1057464929c..d187495ab05 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,6 @@ "scripts": { "dev:site": "hugo server -D -F", "dev:build": "hugo", - "dev:clean": "hugo --cleanDestinationDir", "_build": "npm run _hugo-dev", "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo", "_hugo": "hugo --cleanDestinationDir", From ab35462cf7e02144bb9aaa44371f374de2075625 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Sat, 13 Jun 2026 09:22:50 +0000 Subject: [PATCH 3/3] [CI] standardise Npm managed Hugo Migration Signed-off-by: Heby T Paul --- Makefile | 16 ++++++++-------- package.json | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Makefile b/Makefile index a76f7aee958..199bd297fce 100644 --- a/Makefile +++ b/Makefile @@ -14,6 +14,8 @@ include .github/build/Makefile.show-help.mk +.PHONY: setup check-deps check-go build site clean docker format + ## Install docs.layer5.io dependencies on your local machine. ## See https://gohugo.io/categories/installation setup: @@ -31,17 +33,15 @@ docs-build-production: npm run build:production ## Empty build cache and run docs.layer5.io on your local machine. -clean: check-deps check-go +clean: npm run clean - make site - -.PHONY: setup build site clean check-deps check-go docker + $(MAKE) site check-deps: - @echo "Checking dependencies..." - @command -v npm > /dev/null || (echo "npm is not installed. Please install it before proceeding."; exit 1) - @if [ ! -d "node_modules" ]; then echo "Dependencies not installed. Please run 'make setup' first."; exit 1; fi - @echo "Dependencies are installed." + @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." check-go: @echo "Checking if Go is installed..." diff --git a/package.json b/package.json index d187495ab05..05e06fbc1f9 100644 --- a/package.json +++ b/package.json @@ -9,12 +9,12 @@ "bugs": "https://github.com/layer5io/docs/issues", "spelling": "cSpell:ignore HTMLTEST precheck postbuild -", "scripts": { - "dev:site": "hugo server -D -F", - "dev:build": "hugo", - "_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:-/}\"",