diff --git a/.gitignore b/.gitignore index 2ec8ecb..8638d55 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ # npm resources /node_modules +package-lock.json ## OS Files # Windows diff --git a/README.md b/README.md index 4120dcf..3bba073 100644 --- a/README.md +++ b/README.md @@ -2,34 +2,66 @@ This repository houses the assets used to build and deploy the gRPC website, available at https://grpc.io. The site is built using the [Hugo](https://gohugo.io) static site generator. Check out the [Hugo Quick Start](https://gohugo.io/getting-started/quick-start/) for a quick intro. +## Prerequisites + +- **[Hugo, extended version][hugo-install]** +- **[nvm][]**, the Node Version Manager + ## Serving the site locally -To build and locally serve this site, you need to [install Hugo, extended version](https://gohugo.io/getting-started/installing). Once Hugo is installed: +First install NPM packages: -```bash -make serve +```console +$ npm install ``` -Alternatively, you can run the site using a [Docker](https://docker.com) container: +To build and locally serve this site, you can use **any one** of the following +commands: -```bash -make docker-serve -``` +- Build and serve using [Hugo][], via `make`: + + ```console + $ make serve + ``` + +- Build and serve using [Netlify dev][], which allows you to exercise features + such as site redirects: + + ```console + $ npx netlify dev + ``` + +- Alternatively, you can run the site using a [Docker](https://docker.com) container: + + ```console + $ make docker-serve + ``` ## Publishing the site -The gRPC website is _automatically_ published by [Netlify](https://netlify.com). Any time changes are pushed to the `master` branch, the site is rebuilt and redeployed. +The gRPC website is _automatically_ published by [Netlify][]. Any time changes +are pushed to the `master` branch, the site is rebuilt and redeployed. ## Site content -All of the [Markdown](https://www.markdownguide.org) content used to build the site's documentation, blog, etc. is in the [`content`](content) directory. +All of the [Markdown](https://www.markdownguide.org) content used to build the site's documentation, blog, etc. is in the [content](content) directory. ## Checking links You can check the site's internal links by running this command: -```bash -make check-internal-links +```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. +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. + +[Hugo]: https://gohugo.io +[hugo-install]: https://gohugo.io/getting-started/installing +[Netlify]: https://netlify.com +[Netlify dev]: https://www.netlify.com/products/dev +[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating diff --git a/package.json b/package.json index 2634d99..78750d5 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "devDependencies": { "autoprefixer": "^9.7.6", "bulma": "^0.8.0", + "netlify-cli": "^2.46.0", "postcss-cli": "^7.1.0" } }