The grpc.io site, built using Hugo and hosted on Netlify.
- Hugo, extended edition; match the version specified in netlify.toml
- Node, the latest LTS release. Like Netlify, we use nvm, the
Node Version Manager, to install and manage Node versions:
$ nvm install --lts $ nvm use --lts
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:
$ git clone --recurse-submodules https://github.com/grpc/grpc.io.git
From this point on you'll be working from the grpc.io
directory:
$ cd grpc.io
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:
$ git submodule update --init --recursive --depth 1
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.
Install NPM packages:
$ npm install
Run the following command to have Hugo generate the site files:
$ hugo
The public
folder contains the generated site.
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
$ 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 targets include the following:
serve-drafts
to also serve draft and future pagesserve-production
to server files exactly as they'll appear in production
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:
$ npx netlify dev
If you also want to serve draft and future pages use this command:
$ npx netlify dev -c "hugo serve -DFw"
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.
PR previews are automatically built by Netlify as well. By default, a PR preview is identical to a production build.
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 check the site's internal links by running this command:
$ 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). Any errors
returned from /grpc
links are false negatives that you can ignore.