Auto-generate the hugoautogen workspace via a postinstall hook (#474)

Author: chalin

.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:

README.md

@@ -61,17 +61,23 @@ 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. Because that
+runs a Hugo module command, `npm install` requires the `go` command; see
+[Troubleshooting](#troubleshooting) if it fails.
+
 Then run:
 
 ```bash
-hugo server
+hugo serve
 ```
 
 ## Running a container locally
@@ -121,17 +127,18 @@ 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, for
+example `v0.16.0`:
 
 ```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:
 
 ```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.:
@@ -164,7 +171,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
@@ -180,7 +187,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 /
@@ -196,13 +203,15 @@ 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
 ```
 
 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`.
 

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"

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",
     "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",