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..199bd297fce 100644 --- a/Makefile +++ b/Makefile @@ -14,28 +14,34 @@ 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: 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 - make site - -.PHONY: setup build site clean check-go docker +clean: + npm run clean + $(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." 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..05e06fbc1f9 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:-/}\"",