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 mise (formerly rtx). The handbook repositories provide a .tool-versions configuration file for mise.
  2. Install the mise packages: NodeJS (SASS/CSS), Go (theme development), Vale (linting), Hugo Extended
  3. Install Git, curl, wget for sync scripts.
  4. Install the GitLab CLI for linting jobs.
brew install mise git curl wget glab

mise 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 defined in the .tool-versions file.

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

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

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

eval "$(mise activate zsh)"

If you’re seeing build errors locally which complain about Hugo versions, make sure the output of which hugo points to something like ~/.local/share/mise/installs/hugo-extended/0.151.0/bin/hugo – the shell activation above should help make this work.

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