From 477220e967b71513d8ea534a783c1c0f8cbd77c7 Mon Sep 17 00:00:00 2001 From: Heby T Paul Date: Thu, 11 Jun 2026 12:45:47 +0000 Subject: [PATCH] [CI] Migrate to npm-managed local Hugo and standardise Makefile targets Signed-off-by: Heby T Paul --- CONTRIBUTING.md | 2 +- Makefile | 36 +++++++++++++++++++++++------------- README.md | 5 +++-- package.json | 12 ++++++++---- 4 files changed, 35 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dce2540c7..211caa338 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,7 +98,7 @@ make site #### Building the Site -To build the Academy site for production, ensure you have `Hugo` and `Go` installed. Now, run the following command to build the site: +To build the Academy site for production, ensure you have `npm` and `Go` installed. The local `hugo` binary is managed by `npm`. Ensure you have run `make setup` first, then run the following command to build the site: ```sh make build diff --git a/Makefile b/Makefile index 3baee1f3c..7eea663aa 100644 --- a/Makefile +++ b/Makefile @@ -23,23 +23,33 @@ include .github/build/Makefile.show-help.mk setup: npm install -## Build and run site locally with draft and future content enabled. -site: check-go - hugo server -D -F +## 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." + +## Run on your local machine with draft and future content enabled. +site: check-deps check-go + npm run dev:site + +## Run on your local machine without file watching. +serve: check-deps check-go + npm run dev:serve ## Build site -build: - hugo build +build: check-deps check-go + npm run dev:build ## Build site for local consumption -build-preview: - hugo --baseURL=$(BASEURL) +build-preview: check-deps check-go + npm run dev:build -- --baseURL="$(BASEURL)" ## Empty build cache and run on your local machine. clean: - hugo --cleanDestinationDir - make setup - make site + npm run clean + $(MAKE) site ## Fix Markdown linting issues lint-fix: @@ -61,8 +71,8 @@ check-go: @echo "Go is installed." ## Update the academy-theme package to latest version -theme-update: +theme-update: check-deps echo "Updating to latest academy-theme..." && \ - hugo mod get github.com/layer5io/academy-theme + npm run update:theme -.PHONY: setup build build-preview site clean lint-fix check-go theme-update +.PHONY: setup check-deps build build-preview site serve clean check-go theme-update lint-fix diff --git a/README.md b/README.md index 659f207eb..380bc0210 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ **Layer5 Academy** is the **official content repository** for Layer5's learning platform, hosting all official learning paths, challenges, and certifications. -It is built with [Hugo](https://gohugo.io/) and integrated into a multi-repository architecture for rapid local preview and automated cloud deployment. +It is built with [Hugo](https://gohugo.io/) (managed locally via npm) and integrated into a multi-repository architecture for rapid local preview and automated cloud deployment. --- @@ -59,12 +59,13 @@ The Academy platform is composed of multiple repositories, each with a specific ## Quick Start (Local Preview) > Use this workflow for a fast preview loop when editing Markdown content. +> **Note:** You do not need to install Hugo globally. The required `hugo-extended` binary is managed locally via npm when you run `make setup`. ```bash # Clean up and verify Go module dependencies go mod tidy -# Install necessary tools and modules +# Install necessary tools and modules (including local Hugo) make setup # Start the local Hugo development server diff --git a/package.json b/package.json index ced607503..315fc69d2 100644 --- a/package.json +++ b/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=docsy.work", - "_serve": "npm run _hugo-dev -- --minify serve --renderToMemory", + "_hugo-dev": "hugo --cleanDestinationDir -e dev -DFE", + "_local": "cross-env HUGO_MODULE_WORKSPACE=docsy.work", + "_serve": "npm run _hugo-dev -- server --minify --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.21",