Running the Handbook Locally

Instructions for running the Handbook projects locally

Prerequisites

The handbook development environment requires the extended version of Hugo. The extended version is required for the Docsy GitLab theme as we use SASS for generating the CSS stylesheets for the site. This will also require the installation of Node/NPM.

  1. Install asdf and required plugins. The handbook repositories provide a .tools-version configuration file for asdf.
  2. Install the asdf packages: NodeJS (SASS/CSS), Go (theme development), Vale (linting)
  3. Install Git, curl, wget for sync scripts.
  4. Install the GitLab CLI for linting jobs.
brew install asdf git curl wget glab

asdf plugin add hugo
asdf plugin add nodejs
asdf plugin add golang
asdf plugin add vale
asdf plugin add markdownlint-cli2
asdf install

npm install

Running Hugo

# Be sure to sync-data before building to ensure you have the latest content
./scripts/sync-data.sh

# Build the static website, default output into public/
hugo

# Start a local webserver, listening on localhost:1313
hugo server

Troubleshooting

Permission denied errors

If you encounter an error after running hugo server:

hugo server

Watching for changes in /user/path/{Documents,Library}

<snip>

Built in 35042 ms
Error: error copying static files: open /path/to/handbook/public/webfonts/fa-solid-900.ttf: permission denied

It means that there might be some stale content from previous Hugo runs in public/. You can fix this by running make clean.

Wrong version of Hugo or Hugo not found

When running hugo, you may encounter a hugo not found error or you may notice that your build is using the incorrect version of Hugo. The version of Hugo used to build the site is in the .tool-versions file.

  1. Ensure that you do not have Hugo installed through brew.
  2. See if asdf reshim hugo helps.
  3. If that still doesn’t help, try using asdf exec hugo server.

If you’re still seeing Hugo issues, it may be because your shell isn’t using the asdf versions of dependencies.

If you installed asdf using brew, it should instruct you to add something like the following to your ~/.zshrc file:

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

If you’re seeing build errors locally which complain about Hugo versions, make sure the output of which hugo points to something like ~/.asdf/shims/hugo – the PATH update above should help make this work.

View page source - Edit this page - please contribute. Creative Commons License