[chore]: standardize makefile to npm run calls

.github/workflows/build-and-deploy-site.yml

@@ -43,8 +43,13 @@ jobs:
       - name: Setup site dependencies
         run: make setup
 
+      # Production build. The GitHub Pages base URL is per-fork, so it is passed here directly
+      # rather than baked into config or the standardized scripts.
+      # Mirrors 'npm run build:production' (hugo --cleanDestinationDir --minify --gc).
       - name: Build site
-        run: make build-production BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+        run: |
+          BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+          hugo --cleanDestinationDir --gc --minify --baseURL "${BASE_URL}"
 
       - name: Prepare Pages output
         run: touch public/.nojekyll
@@ -55,4 +60,4 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: gh-pages
           publish_dir: ./public
-          keep_files: true
+          keep_files: true

.github/workflows/build-and-preview-site.yml

@@ -63,12 +63,25 @@ jobs:
         if: github.event.action != 'closed'
         run: make setup
 
+      # The GitHub Pages preview URL is a per-PR subpath, so it is passed here
+      # directly rather than via the standardized scripts (whose build:preview
+      # targets Netlify's DEPLOY_PRIME_URL, not GitHub Pages).
+      # Mirrors 'npm run build:preview' (hugo --cleanDestinationDir -e dev -DFE --minify).
       - name: Build PR preview
         if: github.event.action != 'closed'
         run: |
-          make build-preview BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.pull_request.number }}/"
+          PR_BASE_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.pull_request.number }}/"
+          hugo --cleanDestinationDir -e dev -DFE --minify --baseURL "${PR_BASE_URL}"
           touch public/.nojekyll
 
+      # Preview URLs are public GitHub Pages. Mark the whole deployment
+      # non-indexable so search engines don't crawl preview content.
+      - name: Make preview non-indexable
+        if: github.event.action != 'closed'
+        run: |
+          printf 'User-agent: *\nDisallow: /\n' > public/robots.txt
+          find public -name '*.html' -exec perl -0pi -e 's|<meta name=robots content="index, follow">|<meta name=robots content="noindex, nofollow">|g; s|<meta name="robots" content="index, follow">|<meta name="robots" content="noindex, nofollow">|g; s|</head>|<meta name="robots" content="noindex, nofollow"></head>|i unless /<meta[^>]+name="?robots"?[^>]+noindex, nofollow/i' {} +
+
       - name: Deploy PR preview
         if: github.event.action != 'closed'
         uses: rossjrw/pr-preview-action@v1.6.3
@@ -94,4 +107,4 @@ jobs:
         with:
           preview-branch: gh-pages
           umbrella-dir: pr-preview
-          action: remove
+          action: remove

.github/workflows/build-and-release.yml

@@ -15,7 +15,8 @@ on:
       academy-name:
         description: 'Name of the Academy represented by this repo'
         required: false
-        default: 'Academy'        
+        default: 'Academy'
+        type: string
       version:
         description: 'Module version'
         required: false
@@ -27,27 +28,35 @@ jobs:
 
     steps:
       - name: Checkout site
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
 
-      - name: Setup Hugo Extended
-        uses: peaceiris/actions-hugo@v3
+      - name: Setup Node
+        uses: actions/setup-node@v4
         with:
-          hugo-version: '0.158.0'
-          extended: true
+          node-version: '20'
+          cache: 'npm'
 
       - name: Install dependencies
         run: make setup
 
       - name: Run production build test
-        run: make build
+        run: make build-production
 
       - name: Publish to layer5 academy
         id: academy
         uses: layer5io/academy-build@v0.1.6
         with:
           orgId: ${{ github.event.inputs.orgId || secrets.ACADEMY_ORG_ID }}
           token: ${{ github.event.inputs.token || secrets.ACADEMY_TOKEN }}
-          academy-name: 'Academy'
+          academy-name: ${{ github.event.inputs.academy-name || 'Academy' }}
           version: ${{ github.event.inputs.version != '' && github.event.inputs.version || github.ref_name }}
 
       - name: Show response

.htmltest.yml

@@ -0,0 +1,45 @@
+# htmltest configuration.
+# Checks the built HTML in public/ for broken links, images, and scripts.
+# External links are skipped at runtime via the -s flag in the check:links script.
+
+DirectoryPath: "public"
+
+CheckInternal: true
+CheckExternal: true       # skipped at runtime by -s; left true for when you drop -s
+EnforceHTTPS: true        # still flags real http:// links (e.g. exoscale.com) to fix
+
+# --- Silence intentional or non-blocking findings ---
+
+# Hugo serves pages as directories, so a link to "./foo" (no trailing slash)
+# only causes a redirect, not a break. Don't treat these as errors.
+IgnoreDirectoryMissingTrailingSlash: true
+
+# Alt-text issues are an accessibility backlog, not broken links. Empty alt is
+# valid for decorative images. Re-enable (set these false) when you work the
+# accessibility pass.
+IgnoreAltEmpty: true
+IgnoreAltMissing: true
+
+# Deliberate example URLs in workshop content (intentionally http, not real
+# reachable hosts). These skip HTTPS enforcement; genuine http links elsewhere
+# (exoscale.com, etc.) are NOT listed here, so they still surface for fixing.
+IgnoreHTTPS:
+  - '^http://localhost'
+  - 'votingapp\.(com|cc)'
+  - 'nip\.io'
+  - 'thesecretlivesofdata\.com'
+
+# Directories in public/ to skip entirely (adjust per repo as needed).
+# Theme/shortcode demonstration pages full of intentional example links and
+# placeholder image paths. Not real content; skip the whole section.
+IgnoreDirs:
+  - 'content-formatting-examples'
+
+# Cache external-link results for fast repeat runs (stored under tmp/.htmltest;
+# add tmp/ to .gitignore). Harmless under -s.
+CacheExpires: "336h"
+
+
+# Known-noisy or intentionally-unreachable URLs to ignore (regex).
+# IgnoreURLs:
+#   - "^https://linkedin\\.com/"

Makefile

@@ -15,74 +15,100 @@
 include .github/build/Makefile.core.mk
 include .github/build/Makefile.show-help.mk
 
-#----------------------------------------------------------------------------
-# Academy
-# ---------------------------------------------------------------------------
+# Changes to any main recipe in this Makefile, require a corresponding change in all other repositories subscribed to the 'meshery-academy' topic.
 
-BASE_URL ?=
+# htmltest is fetched and run on demand via 'go run' (no install step). Pin it for
+# reproducible link checks; leave as 'latest' to always use the newest release.
+HTMLTEST_VERSION ?= latest
+export HTMLTEST_VERSION
 
-## Install site dependencies
-setup:
-	@if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then \
-		npm ci; \
-	else \
-		npm install; \
-	fi
-
-## Build and run site locally with draft and future content enabled.
-site: check-deps check-go
-	hugo server -D -F
-
-## Build site for local consumption
-build: check-deps
-	hugo --baseURL="$(BASE_URL)"
-
-## Build preview site with configured base URL
-build-preview: check-deps
-	hugo --baseURL="$(BASE_URL)"
-
-## CI: Build production site output
-build-production: check-deps
-	hugo --baseURL="$(BASE_URL)" --minify -D --buildFuture
-
-## Empty build cache and run on your local machine.
-clean: 
-	hugo --cleanDestinationDir
-	make setup
-	make site
+# ---------------------------------------------------------------------------
+# Academy
+# ---------------------------------------------------------------------------
 
-## Fix Markdown linting issues
-lint-fix:
-	@echo "Running markdownlint-cli2 --fix..."
-	@npx --yes markdownlint-cli2 --fix "**/*.md" "#node_modules" "#public" "#resources"
+# ---------------------------------------------------------------------------
+# MAINTENANCE: Show help for available targets
+# ---------------------------------------------------------------------------
 
 ## Verify required commands and local dependencies are present.
 check-deps:
-	@echo "Checking if 'npm' and 'hugo' are available..."
+	@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; }
-	@command -v hugo > /dev/null || { echo "Error: 'hugo' not found. Please install Hugo."; 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."
 
-## ------------------------------------------------------------
-----MAINTENANCE: Show help for available targets
-
+## 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)
+	@command -v go > /dev/null || { echo "Go is not installed. Please install it before proceeding."; exit 1; }
 	@echo "Go is installed."
 
 ## Update the academy-theme package to latest version
-theme-update:
-	echo "Updating to latest academy-theme..." && \
-	hugo mod get github.com/layer5io/academy-theme
+theme-update: check-go check-deps
+	@echo "Updating to latest academy-theme..."
+	npm run update:theme
+
+# ---------------------------------------------------------------------------
+# LOCAL BUILDS: Show help for available targets
+# ---------------------------------------------------------------------------
+
+## Install site dependencies
+setup:
+	npm install
+
+## Build the site locally with draft and future content enabled.
+build: check-go check-deps
+	npm run build
+
+## Build the site for a deploy preview.
+build-preview: check-go check-deps
+	npm run build:preview
+
+## Build the site for production.
+build-production: check-go check-deps
+	npm run build:production
+
+## Build and run the site locally with live reload (draft and future content enabled).
+site: check-go check-deps
+	npm run site
+
+## Build and serve the site once with the file-watcher off (no live reload).
+site-no-watch: check-go check-deps
+	npm run site:no-watch
+
+## Empty the build cache, reinstall dependencies, and run the site locally.
+clean:
+	npm run clean
+	$(MAKE) setup
+	$(MAKE) site
+
+## Check internal links in the built site (htmltest is fetched on demand via 'go run').
+check-links: check-go check-deps
+	npm run check:links
+
+## Format code using Prettier
+format:
+	npm run format
+
+## Check formatting without writing changes.
+format-check:
+	npm run format:check
+
+## Fix Markdown linting issues
+lint-fix:
+	npx --yes markdownlint-cli2 --fix "content/**/*.md"
 
 .PHONY: \
 	setup \
-	site \
 	build \
 	build-preview \
 	build-production \
+	site \
+	site-no-watch \
 	clean \
+	check-links \
+	format \
+	format-check \
 	lint-fix \
 	check-deps \
 	check-go \

go.mod

@@ -3,7 +3,7 @@ module github.com/layer5io/academy-example
 go 1.24.5
 
 // Uncomment line below when testing changes to the academy theme
-replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme
+// replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme
 
 replace github.com/FortAwesome/Font-Awesome v4.7.0+incompatible => github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3