Running the Handbook Locally
Use this guide to preview the handbook with tools installed on your computer. You only need Git and an editor to edit files and use CI/CD for feedback. If you prefer to run the preview tools in a container, follow the Docker guide.
Prerequisites
The setup below walks through macOS. For another operating system, use the linked installation guides and the activation instructions for your shell.
You will use a terminal, an app where you type commands and press Return to run them. On macOS, open Terminal from Applications > Utilities. Run each command separately and wait for it to finish before continuing. If a command reports an error, use the troubleshooting guide.
Hugo turns the handbook’s Markdown files into web pages. The theme needs Hugo
Extended to process its stylesheets. This will also require the installation of Node/NPM.
You do not need to choose their versions yourself: mise reads the versions saved
in the repository’s .tool-versions file and installs them for you.
Install the macOS command-line tools
Git downloads the repository and tracks your edits. Make provides shortcuts for running the preview. Both come with Apple’s Command Line Tools.
Check whether they are installed:
git --version
make --version
If they are missing, run this command and complete the installation window:
xcode-select --install
Then run the version checks again. macOS also includes curl, which the data
synchronization script uses to download files.
Install Homebrew and mise
Homebrew installs command-line tools on your computer.
Follow the Homebrew installation guide, including
the installer’s Next steps. These make the brew command available in your terminal.
Open a new terminal and check the installation:
brew --version
If a version number appears, install mise, Git, curl, Make, and the GitLab CLI:
brew install mise git curl make glab
Mise manages the tool versions for each project. Confirm it is available:
mise --version
Activate mise
Activation lets your terminal find the tools installed by mise. For macOS’s default
zsh shell, run the following command once. It adds the activation line to ~/.zshrc,
the settings file loaded when you open a terminal:
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
If you already activated mise, skip this command. For another shell, follow the mise activation instructions. Open a new terminal before continuing.
Open the repository and install its tools
Clone the repository if you have not already.
Open the cloned folder in your editor. For VS Code as editor, use Terminal > New Terminal.
This opens a terminal in that folder, also called the repository root.
It contains files such as package.json and .tool-versions.
Run this command from that folder:
mise install
Wait for the downloads and installation to finish. If mise asks whether you trust the configuration, confirm only after checking that you are in the handbook repository you intended to clone. This installs Hugo Extended, Node.js and npm, Go for theme modules, and the tools used for writing checks.
Check that Hugo is available:
hugo version
The output should include extended and the Hugo version listed in .tool-versions.
Running Hugo
After completing setup, run this command from the repository folder:
make view
It installs npm dependencies, makes the theme’s tools available, synchronizes the required data, and starts the preview. You do not need to run the individual commands below first.
The first build can take several minutes. Wait for Hugo to report that its web server is available, then open http://localhost:1313/ in your browser. Keep the terminal running while you edit. Saving a file rebuilds the preview. Press Control+C in the terminal when you want to stop.
To preview again, open a terminal in the repository folder and run make view.
Makefile shortcuts
To generate the website files in the public/ folder without starting a preview, run:
make build
This also installs dependencies and synchronizes data automatically.
Run the commands individually
For troubleshooting or more control over each step, you can run the preparation
and Hugo commands yourself. Use these instead of make view, from the repository folder:
-
Install the project’s dependencies, including Dart Sass, which builds the theme’s styles:
npm ci -
Make those tools available in this terminal.
PATHis the list of folders your terminal searches for commands;$PWDmeans your current folder:export PATH="$PWD/node_modules/.bin:$PATH" -
Download the data used by handbook pages, such as team member information:
./scripts/sync-data.sh -
Start the preview server:
hugo server
Run the export command again in each new terminal. Run npm ci again after
changes to the dependency lockfile, and the sync script when you need fresh data.
Check your edits
Follow Linting content to check formatting, writing, and links. Your merge request also runs these checks in CI/CD. If a workflow asks for the GitLab CLI, follow its authentication guide. GitLab CLI access is separate from running the preview.
Updating theme dependencies (maintainers)
make view and make build install dependencies with npm ci and synchronize
the required data automatically. You can also use make prep as a shortcut for
npm ci when installing dependencies separately.
After changing the Docsy module version, refresh its npm workspace and lockfile:
hugo mod tidy
hugo mod npm pack
npm install
Commit go.mod, go.sum, package.json, package-lock.json, and
the files under packages/hugoautogen/. Normal checkouts and CI use npm ci.
The installation script runs npm rebuild sass-embedded to ensure that the sass
command points to the embedded compiler. The optional JavaScript fallback can
otherwise claim the same executable name and make Hugo fail with unexpected EOF.
See the Docsy 0.17 upgrade guide for the Dart Sass and Font Awesome changes.
Troubleshooting
See local development troubleshooting for build errors and recovery commands.
Permission denied errors
See permission denied when copying static files.
Wrong version of Hugo or Hugo not found
See Hugo is missing or the wrong version runs.
0f66367e)
