From adf50f956488078cf86cd8acb724ed54d6f2fd8a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 14:11:37 -0400 Subject: [PATCH 1/4] Auto-generate the hugoautogen workspace via a postinstall hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replaces the explicit `install:all` double-install with an automatic `postinstall` hook, so a single `npm install` regenerates and installs the git-ignored `hugoautogen` workspace — restoring a plain `npm install` for contributors, Netlify, and CI. - Adds `postinstall`: `npm run update:docsy:pack -- --ignore-scripts`; the `--ignore-scripts` on the nested install keeps the hook from recursing. - Reverts `netlify.toml`, the links workflow, and the README to a plain `npm install`, and drops the now-redundant `install:all` script. - Documents in the README why this single install also builds the theme's npm asset workspace (Hugo is sourced via npm; the theme's assets are discovered through Hugo modules). --- .github/workflows/links.yaml | 2 +- README.md | 10 +++++++--- netlify.toml | 4 ++-- package.json | 2 +- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.github/workflows/links.yaml b/.github/workflows/links.yaml index 42a8941302e..0718da1c034 100644 --- a/.github/workflows/links.yaml +++ b/.github/workflows/links.yaml @@ -27,7 +27,7 @@ jobs: cache: npm cache-dependency-path: package.json - - run: npm run install:all + - run: npm install --omit=optional - name: Install lychee env: diff --git a/README.md b/README.md index dffb484ad1f..ab6c16ea0b8 100644 --- a/README.md +++ b/README.md @@ -61,13 +61,17 @@ your environment in our guide. Once you've made your working copy of the site repo, from the repo root folder, -first install the npm dependencies, including the Bootstrap and Font Awesome -assets that the theme sources as npm packages: +install the npm dependencies, including the Bootstrap and Font Awesome assets +that the theme sources as npm packages: ```bash -npm run install:all +npm install ``` +Because this site fetches Hugo itself from npm and discovers the theme's npm +assets through Hugo modules, a `postinstall` hook runs `hugo mod npm pack` and a +second install, so this single `npm install` sets everything up. + Then run: ```bash diff --git a/netlify.toml b/netlify.toml index 68ad5219ca3..7898ef86a67 100644 --- a/netlify.toml +++ b/netlify.toml @@ -2,11 +2,11 @@ # (https://gohugo.io/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify) [build] -command = "npm run install:all && npm run build:preview" +command = "npm run build:preview" publish = "public" [build.environment] GO_VERSION = "1.22.2" [context.production] -command = "npm run install:all && npm run build:production" +command = "npm run build:production" diff --git a/package.json b/package.json index cf15ce447bf..07eb5272020 100644 --- a/package.json +++ b/package.json @@ -35,10 +35,10 @@ "fix:format:diff": "npm run fix:format", "fix:format": "npm run _check:format -- --write", "fix": "npm run fix:format", - "install:all": "echo 'INFO: first install is for hugo from hugo-extended' && npm install && hugo mod npm pack && npm install", "local": "npm run _local -- npm run", "make:public": "git init -b main public", "post_hugo": "npm run _fix:permissions", + "postinstall": "npm run update:docsy:pack -- --ignore-scripts", "postupdate:docsy:main": "npm run _update:docsy:post", "postupdate:docsy:mod": "npm run _update:docsy:post", "precheck:links:internal": "npm run build", From bba26b83aee84713aaa62710ce709ba4dddea7f8 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 20:32:38 -0400 Subject: [PATCH 2/4] Move --ignore-scripts to update:docsy:pack, README tweaks --- README.md | 12 ++++++------ package.json | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ab6c16ea0b8..37e3ea72cee 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ second install, so this single `npm install` sets everything up. Then run: ```bash -hugo server +hugo serve ``` ## Running a container locally @@ -125,11 +125,11 @@ Make sure your installed go version is `1.18` or higher. Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your -site's root folder. +site's root folder. Replace $VERSION with the version you want to use. ```shell cd root-of-your-site -git clone --branch v0.12.0 https://github.com/google/docsy.git ../docsy +git clone --branch $VERSION https://github.com/google/docsy.git ../docsy ``` Now run: @@ -168,7 +168,7 @@ characters '//' so that this line takes effect. As you run the website locally, you may run into the following error: ```console -$ hugo server +$ hugo serve WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information. Start building sites … hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio @@ -184,7 +184,7 @@ of the user guide for instructions on how to install Hugo. Or you may be confronted with the following error: ```console -$ hugo server +$ hugo serve INFO 2021/01/21 21:07:55 Using config file: Building sites … INFO 2021/01/21 21:07:55 syncing static files to / @@ -200,7 +200,7 @@ of the user guide for instructions on how to install Hugo. Or you may encounter the following error: ```console -$ hugo server +$ hugo serve Error: failed to download modules: binary with name "go" not found ``` diff --git a/package.json b/package.json index 07eb5272020..188c7793bb7 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "local": "npm run _local -- npm run", "make:public": "git init -b main public", "post_hugo": "npm run _fix:permissions", - "postinstall": "npm run update:docsy:pack -- --ignore-scripts", + "postinstall": "npm run update:docsy:pack", "postupdate:docsy:main": "npm run _update:docsy:post", "postupdate:docsy:mod": "npm run _update:docsy:post", "precheck:links:internal": "npm run build", @@ -51,7 +51,7 @@ "test": "npm run test-and-fix", "update:docsy:main": "hugo mod get -u github.com/google/docsy/theme@main", "update:docsy:mod": "hugo mod get -u github.com/google/docsy/theme", - "update:docsy:pack": "hugo mod npm pack && npm install", + "update:docsy:pack": "hugo mod npm pack && npm install --ignore-scripts", "update:hugo": "npm install --save-dev --save-exact hugo-extended@latest", "update:main": "npm run update:packages && npm run update:docsy:main", "update:packages:not-hugo": "npm run update:packages -- -x hugo-extended", From 751ac0ea60a508be61812c757a64cbe2b3ca6c01 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 20:37:09 -0400 Subject: [PATCH 3/4] Feedback --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37e3ea72cee..b95d2af2309 100644 --- a/README.md +++ b/README.md @@ -125,11 +125,12 @@ Make sure your installed go version is `1.18` or higher. Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your -site's root folder. Replace $VERSION with the version you want to use. +site's root folder. Replace VERSION with the version you want to use, for +example `v0.16.0`: ```shell cd root-of-your-site -git clone --branch $VERSION https://github.com/google/docsy.git ../docsy +git clone --branch VERSION https://github.com/google/docsy.git ../docsy ``` Now run: From e9fb75ed4eb753a8bb0f238616e4726a2ce6df76 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 20:49:29 -0400 Subject: [PATCH 4/4] README: document that install needs Go, and tidy commands - Notes that `npm install` now requires Go, since the `postinstall` hook runs `hugo mod npm pack`, and broadens the existing `go`-not-found troubleshooting entry to say it can surface at install time, not only when serving. - Aligns the local-clone command to `hugo serve`, matching the rest of the README and the `serve` npm script. - Formats the `VERSION` placeholder as italic code, per the Google placeholder style. --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b95d2af2309..1fc0b0794ce 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,9 @@ npm install Because this site fetches Hugo itself from npm and discovers the theme's npm assets through Hugo modules, a `postinstall` hook runs `hugo mod npm pack` and a -second install, so this single `npm install` sets everything up. +second install, so this single `npm install` sets everything up. Because that +runs a Hugo module command, `npm install` requires the `go` command; see +[Troubleshooting](#troubleshooting) if it fails. Then run: @@ -125,7 +127,7 @@ Make sure your installed go version is `1.18` or higher. Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your -site's root folder. Replace VERSION with the version you want to use, for +site's root folder. Replace _`VERSION`_ with the version you want to use, for example `v0.16.0`: ```shell @@ -136,7 +138,7 @@ git clone --branch VERSION https://github.com/google/docsy.git ../docsy Now run: ```shell -HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**" +HUGO_MODULE_WORKSPACE=docsy.work hugo serve --ignoreVendorPaths "**" ``` or, when using npm, prepend `local` to the script you want to invoke, e.g.: @@ -207,7 +209,9 @@ Error: failed to download modules: binary with name "go" not found ``` This error occurs if the `go` programming language is not available on your -system. See this +system. Because `npm install` runs `hugo mod npm pack` (via a `postinstall` +hook), this can also surface during installation, not only when serving. See +this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.