chore(make): standardize Makefile structure

Makefile

@@ -12,40 +12,151 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+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
 
+## 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 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
+
+## Run docs.layer5.io on your local machine 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: check-deps check-go
+	npm run dev:build
 
-docs-build-production:
-	npm run build:production
+## Build docs.layer5.io for production with optional base URL.
+build-production: check-deps
+	set -e; \
+	if [ -n "$(BASE_URL)" ]; then \
+		base_url="$(BASE_URL)"; \
+		base_url="$${base_url%/}/"; \
+		npm run build:production -- --gc --baseURL "$$base_url"; \
+	else \
+		npm run build:production -- --gc; \
+	fi
 
 ## Empty build cache and run docs.layer5.io on your local machine.
-clean: 
-	hugo --cleanDestinationDir
-	make site
-
-.PHONY: setup build site clean check-go docker
+clean: check-deps
+	npm run dev:clean
+	$(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
+
+## Install base OS dependencies needed in Docker-based docs builds.
+docker-install-base-deps:
+	apt-get update
+	apt-get install -y --no-install-recommends nodejs npm ca-certificates wget xz-utils
+	rm -rf /var/lib/apt/lists/*
+
+## Install Node.js dependencies in CI or container contexts.
+docker-deps:
+	npm ci
+
+## Download and unpack a specific Hugo Extended binary for Docker builds.
+docker-download-hugo:
+	@test -n "$(HUGO_VERSION)" || (echo "HUGO_VERSION is required"; exit 1)
+	@test -n "$(TARGETARCH)" || (echo "TARGETARCH is required"; exit 1)
+	mkdir -p /tmp/hugo
+	wget -O /tmp/hugo/hugo.tar.gz "https://github.com/gohugoio/hugo/releases/download/v$(HUGO_VERSION)/hugo_extended_$(HUGO_VERSION)_linux-$(TARGETARCH).tar.gz"
+	tar -xf /tmp/hugo/hugo.tar.gz -C /tmp/hugo hugo
+
+## Build the docs site for Docker output with optional environment/base URL overrides.
+docker-build:
+	set -e; \
+	args="--gc --minify -d /out"; \
+	if [ -n "$(HUGO_ENV)" ]; then args="$$args -e $(HUGO_ENV)"; fi; \
+	if [ -n "$(DOCS_URL)" ]; then args="$$args -b $(DOCS_URL)"; fi; \
+	hugo $$args
+
+## Ensure Hugo generated the stats file required by downstream tooling.
+docker-validate-stats:
+	@test -f /src/hugo_stats.json || (echo "hugo_stats.json was not generated"; exit 1)
+
+## Lint Markdown content during Docker-based checks.
+docker-lint:
+	npx --yes markdownlint-cli2 \
+		"content/**/*.md"
+
+## Install htmltest binary for link validation in container environments.
+docker-install-htmltest:
+	@test -n "$(HTMLTEST_VERSION)" || (echo "HTMLTEST_VERSION is required"; exit 1)
+	GOBIN=/usr/local/bin go install github.com/wjdp/htmltest@v$(HTMLTEST_VERSION)
+
+## Run htmltest against the generated site output.
+docker-htmltest:
+	@test -n "$(HTMLTEST_DIR)" || (echo "HTMLTEST_DIR is required"; exit 1)
+	@if [ -f /src/.htmltest.yml ]; then \
+		cd "$(HTMLTEST_DIR)" && htmltest --conf /src/.htmltest.yml; \
+	else \
+		cd "$(HTMLTEST_DIR)" && htmltest; \
+	fi
+
+## Update Hugo modules and vendor dependencies for Docker builds.
+docker-update-modules:
+	set -ex; \
+	if [ -n "$(MODULE)" ]; then \
+		module_base="$${MODULE%@*}"; \
+		hugo mod get "$(MODULE)"; \
+		resolved=$$(go list -m "$$module_base" | awk '{print $$1 "@" $$2}'); \
+		go mod edit -replace "$$module_base=$$resolved"; \
+	else \
+		echo "no module set"; \
+	fi; \
+	hugo mod vendor
+
+## Build docs while ignoring vendored paths for an upstream module.
+docker-build-upstream:
+	@test -n "$(UPSTREAM_MODULE_NAME)" || (echo "UPSTREAM_MODULE_NAME is required"; exit 1)
+	@test -n "$(UPSTREAM_REPO)" || (echo "UPSTREAM_REPO is required"; exit 1)
+	@test -n "$(UPSTREAM_COMMIT)" || (echo "UPSTREAM_COMMIT is required"; exit 1)
+	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
 
-## Format code using Prettier
-format:
-	npm run format
+.PHONY: \
+	setup \
+	check-deps \
+	build \
+	build-production \
+	site \
+	serve \
+	clean \
+	check-go \
+	format \
+	docker \
+	docker-install-base-deps \
+	docker-deps \
+	docker-download-hugo \
+	docker-build \
+	docker-validate-stats \
+	docker-lint \
+	docker-install-htmltest \
+	docker-htmltest \
+	docker-update-modules \
+	docker-build-upstream

package.json

@@ -17,6 +17,10 @@
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${BASE_URL:-${DEPLOY_PRIME_URL:-/}}\"",
     "build:production": "npm run _hugo -- --minify --baseURL \"${BASE_URL:-/}\"",
     "build": "npm run _build",
+    "dev:site": "npm run serve",
+    "dev:serve": "npm run _hugo -- --minify --watch=false serve",
+    "dev:build": "npm run _build",
+    "dev:clean": "npm run clean",
     "check:links:all": "HTMLTEST_ARGS= npm run _check:links",
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public/* resources",