From 0a616aceb0771967da0b0bc101982d57e7a85da6 Mon Sep 17 00:00:00 2001 From: Ashley <8253488+mrjones-plip@users.noreply.github.com> Date: Tue, 19 Mar 2024 14:46:21 -0700 Subject: [PATCH] fix (#1302): Update troubleshooting steps for hugo "key kind not allowed" error (#1312) * Update troubleshooting steps for new hugo "key kind not allowed" error * add hugo version pinning to troubleshooting --- README.md | 2 +- troubleshooting.md | 17 ++++++++++++++--- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b8122f9db..52d8dd648 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ If using `asdf` fails you can try installing Hugo manually. To install, follow t 1. Preview your site in your browser at: http://localhost:1313/ 1. As you make changes to the site, your browser will automatically reload your local dev site so you can easily and quickly see your changes. -MacOS users getting errors when running `hugo server`, please see our [Troubleshooting guide](./troubleshooting.md). +Any users who experience errors running `hugo server`, please see our [Troubleshooting guide](./troubleshooting.md). ## Link Checking [Optional] diff --git a/troubleshooting.md b/troubleshooting.md index 34c7bd1bf..0859aa463 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -1,12 +1,12 @@ # Troubleshooting -The first thing to check, regardless of your OS, is that you are running the latest version of Hugo and that it's the Extended version. You can do this by running the following command... +The first thing to check, regardless of your OS, is that you are running the correct version of Hugo and that it's the Extended version: ```shell hugo version ``` -...which should return something like: +This will show something like: ```shell @@ -17,6 +17,17 @@ In this example, `0.108.0` is the release and `+extended` indicates that it is t You can see the list of Hugo releases [here](https://github.com/gohugoio/hugo/releases). +## Which `hugo` version to run + +There's currently an [issue running versions later than `0.123` or later](https://github.com/medic/cht-docs/issues/1302). You should run `0.122` to avoid the error until this issue is fixed. Follow these steps to install the older `0.122` version. While they mention `snap` which is specific to Linux, the install steps should work for macOS and Windows with WSL 2 as well: + +1. Remove the too new verison of `hugo`. If you used `snap`, you can uninstall with: `sudo snap remove hugo` +2. Download the specific `hugo` tarball: `wget https://github.com/gohugoio/hugo/releases/download/v0.122.0/hugo_extended_0.122.0_linux-amd64.tar.gz` +3. Uncompressed it: `tar xvzf hugo_extended_0.122.0_linux-amd64.tar.gz` +4. Move the binary into your `$PATH`: `sudo mv hugo /usr/local/bin` + +If you were running the `snap` version of `hugo`, you may need to install `go` now as it was removed with `hugo`. This should work with `sudo snap install go`. Other platforms that need to install Go should see their [install docs](https://golang.org/doc/install). + ## MacOS @@ -58,4 +69,4 @@ MacOS M1 users encountering `Error: Error building site: POSTCSS: failed to tran ```shell npm install postcss-cli -``` \ No newline at end of file +```