diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f743db3b4a..3a84474be89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,36 +43,8 @@ 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:** 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 00c97e9e2de..b90f2a1709e 100644 --- a/Makefile +++ b/Makefile @@ -15,10 +15,13 @@ 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 +# --------------------------------------------------------------------------- +# Docs +# --------------------------------------------------------------------------- + +# --------------------------------------------------------------------------- +# MAINTENANCE: Show help for available targets +# --------------------------------------------------------------------------- ## Verify required commands and local dependencies are present. check-deps: @@ -27,20 +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." -## Run docs.layer5.io on your local machine in serve mode (without file watching). -serve: check-deps check-go - npm run dev:serve +#---------------------------------------------------------------------------- +# 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)"; \ @@ -50,21 +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: check-deps - npm run dev:clean +clean: + npm run clean + $(MAKE) setup $(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 +#---------------------------------------------------------------------------- +# 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 @@ -135,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 \ diff --git a/README.md b/README.md index bee859536b8..c53cee9dd10 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ 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. Now to setup and run the site locally execute: diff --git a/package.json b/package.json index 328d1b27ad7..671143e8562 100644 --- a/package.json +++ b/package.json @@ -9,10 +9,12 @@ "bugs": "https://github.com/layer5io/docs/issues", "spelling": "cSpell:ignore HTMLTEST precheck postbuild -", "scripts": { - "_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:-/}\"",