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/5] [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/5] 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/5] [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:-/}\"", From 31d7b874f6898de7fa4c23a1af4277537237ea16 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Fri, 3 Jul 2026 09:21:48 +0000 Subject: [PATCH 4/5] chore(Makefile): Standardize targets and resolve merge conflict Signed-off-by: Heby T Paul --- Makefile | 74 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/Makefile b/Makefile index 31cbcda0cdc..b90f2a1709e 100644 --- a/Makefile +++ b/Makefile @@ -15,12 +15,13 @@ include .github/build/Makefile.core.mk include .github/build/Makefile.show-help.mk -.PHONY: setup check-deps check-go build site clean docker format +# --------------------------------------------------------------------------- +# Docs +# --------------------------------------------------------------------------- -## Install docs.layer5.io dependencies on your local machine. -## See https://gohugo.io/categories/installation -setup: - npm install +# --------------------------------------------------------------------------- +# MAINTENANCE: Show help for available targets +# --------------------------------------------------------------------------- ## Verify required commands and local dependencies are present. check-deps: @@ -29,16 +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." + +#---------------------------------------------------------------------------- +# 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)"; \ @@ -48,27 +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: npm run clean + $(MAKE) setup $(MAKE) site -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." - -## 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 @@ -139,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 \ From 99aa6b12f712d0d04a8e2e75ca0ec429362d4217 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Fri, 3 Jul 2026 09:28:24 +0000 Subject: [PATCH 5/5] chore(docs): address review feedback regarding standardisation and redundant notes Signed-off-by: Heby T Paul --- CONTRIBUTING.md | 2 +- README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8bb224d395f..3a84474be89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ Make sure you have the following prerequisites installed on your operating syste go version ``` -**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/README.md b/README.md index 47df6f3dc18..c53cee9dd10 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, 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. +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: -1. `make setup` (This installs local dependencies, including Hugo) +1. `make setup` 2. `make site` 3. visit http://localhost:1313