From 0aefbcd09265f1989628fc9743d7048cd356efdb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 19 Aug 2021 14:24:15 -0400 Subject: [PATCH] Greatly simplify build and build instructions (#830) --- Makefile | 50 ++++++------------ README.md | 140 ++++++++++---------------------------------------- check_hugo.sh | 6 --- netlify.toml | 9 ++-- package.json | 16 ++++-- 5 files changed, 59 insertions(+), 162 deletions(-) delete mode 100755 check_hugo.sh diff --git a/Makefile b/Makefile index 66d542b..e23ceb9 100644 --- a/Makefile +++ b/Makefile @@ -1,40 +1,20 @@ -DRAFT_ARGS = --buildDrafts --buildFuture -BUILD_ARGS = --minify -ifeq (draft, $(or $(findstring draft,$(HEAD)),$(findstring draft,$(BRANCH)))) -BUILD_ARGS += $(DRAFT_ARGS) +HTMLTEST_DIR=tmp +HTMLTEST?=htmltest # Specify as make arg if different +# Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy +ifeq (, $(shell which $(HTMLTEST))) +GET_LINK_CHECKER_IF_NEEDED=get-link-checker +override HTMLTEST=$(HTMLTEST_DIR)/bin/htmltest endif -clean: - rm -rf public/* resources +check-internal-links: $(GET_LINK_CHECKER_IF_NEEDED) + $(HTMLTEST) -serve: - @./check_hugo.sh - hugo serve +check-all-links: $(GET_LINK_CHECKER_IF_NEEDED) + $(HTMLTEST) --conf .htmltest.external.yml -serve-drafts: - @./check_hugo.sh - hugo serve $(DRAFT_ARGS) +clean-htmltest-dir: + rm -Rf $(HTMLTEST_DIR) -serve-production: clean - @./check_hugo.sh - hugo serve -e production --minify - -production-build: clean - @./check_hugo.sh - hugo --minify - -preview-build: clean - @./check_hugo.sh - hugo --baseURL $(DEPLOY_PRIME_URL) \ - -e development $(BUILD_ARGS) - -link-checker-setup: - curl https://raw.githubusercontent.com/wjdp/htmltest/master/godownloader.sh | bash - -run-link-checker: - bin/htmltest - -check-internal-links: production-build link-checker-setup run-link-checker - -check-all-links: production-build link-checker-setup - bin/htmltest --conf .htmltest.external.yml +get-link-checker: + rm -Rf $(HTMLTEST_DIR)/bin + curl https://htmltest.wjdp.uk | bash -s -- -b $(HTMLTEST_DIR)/bin diff --git a/README.md b/README.md index 963fcb8..d6d4039 100644 --- a/README.md +++ b/README.md @@ -4,148 +4,64 @@ The [grpc.io][] site, built using [Hugo][] and hosted on [Netlify][]. ## Build prerequisites -### 1. Install the following tools - -- **[Hugo, extended edition][hugo-install]**; match the version specified in - [netlify.toml](netlify.toml) -- **Node**, the latest [LTS release][]. Like Netlify, we use **[nvm][]**, the - Node Version Manager, to install and manage Node versions: - ```console - $ nvm install --lts - ``` - -### 2. Clone this repo _and_ its submodules - -> IMPORTANT: This repo has **recursive git _submodules_**, which affects how you -> clone it. - -The _simplest_ way to get a full copy of this repo is to clone the repo _and_ -its submodules _at the same time_ by running this command from a command shell / -window: +To build and serve the site, you'll need the latest [LTS release][] of **Node**. +Like Netlify, we use **[nvm][]**, the Node Version Manager, to install and +manage Node versions: ```console -$ git clone --recurse-submodules https://github.com/grpc/grpc.io.git -``` -### 3. Change directories - -From this point on you'll be working from the `grpc.io` directory: - -```console -$ cd grpc.io -``` -### 4. Did you get the submodules? - -Forgetting to clone the submodules is a common error. - -If you forgot the `--recurse-submodules` option when you ran the `clone` command -given in step 2 above or, if you cloned the repo using another method, as -described in [Cloning a repository][], then you'll need to fetch the repo's -submodules. - -To (recursively) fetch the submodules, run the following command from the -`grpc.io` directory: - -```console -$ git submodule update --init --recursive --depth 1 +$ nvm install --lts ``` -> NOTE: Unsure if you've fetched the submodules? The Git command above is -> idempotent, so you can safely (re-)run it -- if you already have the -> submodules, it will have no effect. +## Setup -### 5. Run installation scripts - -Install NPM packages: - -```console -$ npm install -``` + 1. Clone or download a copy of this repo. + 2. From a terminal window, change to the cloned or unzipped repo directory. + 3. Get NPM packages and git submodules, including the the [Docsy][] theme: + ```console + $ npm install + ``` ## Build the site Run the following command to have Hugo generate the site files: ```console -$ hugo +$ npm run build ``` -The `public` folder contains the generated site. +You'll find the generated site files in the `public` folder. ## Serve the site locally -To locally serve this site, use **one** of the following commands. -> **Note**: Hugo serves pages from memory by default, so if you want to -> (re-)generate the website files to disk, use the build command above. - -### a) Serve using [Hugo][] via `make` +To locally serve the site at [localhost:8888][], run the following command: ```console -$ make serve -hugo server -Start building sites … -... -Environment: "development" -Serving pages from memory -... -Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) -Press Ctrl+C to stop -``` - -This generates _unminified_ site pages. Other [Makefile](Makefile) targets -include the following: - -- `serve-drafts` to also serve draft and future pages -- `serve-production` to server files exactly as they'll appear in production - -### b) Serve using Netlify dev - -[Netlify dev][] uses Hugo under the hood to serve the site, but it also creates -a proxy (at port 8888 by default), to handle [site redirects][]: - -```console -$ npx netlify dev -``` - -If you also want to serve draft and future pages use this command: - -```console -$ npx netlify dev -c "hugo serve -DFw" +$ npm run serve ``` ## Site deploys and PR previews -Commits to the `main` branch are _automatically_ published by [Netlify][]. You -can see deploy logs and more from the [Netlify gRPC Team dashboard][], provided -you have the necessary permissions. +If you submit a PR, Netlify will automatically create a [deploy preview][] so +that you can review your changes. Once your PR is merged, Netlify automcatically +deploys to the production site [grpc.io][]. -_PR previews_ are automatically built by [Netlify][] as well. By default, a PR -preview is identical to a production build. +> **Note**: PR previews include _draft pages_, but production builds do not. -If you want draft and future pages to also appear in a PR preview, then make -sure that the word "draft" appears in the branch name used to create the PR. +You can see deploy logs and more from the [Netlify gRPC Team dashboard][], +provided you have the necessary permissions. -## Checking links +## Contribute -You can check the site's internal links by running this command: +We welcome issues and PRs! For details, see [Contribute][]. -```console -$ make check-internal-links -``` - -This deletes the generated `public` directory, builds the "production" version -of the site, and verifies that internal links are valid. Please note that -internal links prefixed with `/grpc` do not work in your local environment -(there are redirects applied by [Netlify](https://netlify.com)). Any errors -returned from `/grpc` links are false negatives that you can ignore. - -[Cloning a repository]: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository +[Contribute]: https://grpc.io/community/#contribute +[deploy preview]: https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/ +[Docsy]: https://www.docsy.dev [grpc.io]: https://grpc.io [Hugo]: https://gohugo.io -[hugo-install]: https://gohugo.io/getting-started/installing +[localhost:8888]: http://localhost:8888 [LTS release]: https://nodejs.org/en/about/releases/ -[Netlify]: https://netlify.com -[Netlify dev]: https://www.netlify.com/products/dev [Netlify gRPC Team dashboard]: https://app.netlify.com/teams/grpc/overview +[Netlify]: https://netlify.com [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating -[site redirects]: layouts/index.redirects diff --git a/check_hugo.sh b/check_hugo.sh deleted file mode 100755 index 0391326..0000000 --- a/check_hugo.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash - -set -e - -command -v hugo >/dev/null || (echo "Hugo extended must be installed on your system." >/dev/stderr; exit 1) -hugo version | grep -i extended >/dev/null || (echo "Your Hugo installation does not appear to be extended." >/dev/stderr; exit 1) diff --git a/netlify.toml b/netlify.toml index 90e1f30..b0c4f8c 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,12 +1,9 @@ [build] publish = "public" -command = "make production-build" - -[build.environment] -HUGO_VERSION = "0.82.0" +command = "npm run build:production" [context.branch-deploy] -command = "make preview-build" +command = "npm run build:preview" [context.deploy-preview] -command = "make preview-build" +command = "npm run build:preview" diff --git a/package.json b/package.json index dd7fbad..69649f4 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,21 @@ { "scripts": { - "get-submodules": "git submodule update --init --recursive --depth 1", - "preinstall": "npm run get-submodules" + "_check-links": "make check-internal-links", + "build:preview": "hugo --cleanDestinationDir -DFE --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", + "build:production": "hugo --cleanDestinationDir --minify", + "build": "hugo --cleanDestinationDir -e dev -DFE", + "check-links": "npm run _check-links", + "postbuild:preview-DISABLED": "npm run _check-links", + "precheck-links": "npm run build", + "preinstall": "npm run submodule:get", + "serve": "netlify dev -c \"hugo serve --minify -DFE -w\"", + "submodule:get": "git submodule update --init --recursive --depth 1", + "submodule:update": "git submodule update --remote --recursive --depth 1" }, "devDependencies": { "autoprefixer": "^10.3.1", - "netlify-cli": "^3.39.4", + "hugo-extended": "0.82.0", + "netlify-cli": "^6.6.1", "postcss": "^8.3.6", "postcss-cli": "^8.3.1" }