From de6ec7bbe31f244319ca936d7fd004643a1c34ff Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 09:02:54 -0400 Subject: [PATCH 1/4] Stop committing the generated hugoautogen workspace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Stops committing `packages/hugoautogen/package.json` — `hugo mod npm pack` generates it to aggregate the theme's npm deps (Bootstrap, Font Awesome), so a committed copy is just generated noise that can drift. - Adds `install:all` (`npm install && hugo mod npm pack && npm install`) to regenerate the manifest on demand, and routes every from-scratch build path through it, since a bare `npm install` silently prunes the theme deps (exit 0, no error) when the manifest is absent: - CI (`links.yaml`) installs via `npm run install:all`; this drops the old `--omit=optional`, so the links job now also installs the optional dev deps (`prettier`, `npm-check-updates`) — a deliberate, negligible cost for one canonical build path. - Netlify (`netlify.toml`) prefixes both build commands with it. - README lists it as a prerequisite for running the site locally. - An echo notes that the double install exists only because Hugo, which runs the pack, is itself an npm dependency. - Ignores the generated `packages/hugoautogen/` directory. - Simplifies the freshness guard `check:generated` to `_diff:fail` now that no generated file is committed; it still guards the committed `.lycheecache`. --- .github/workflows/links.yaml | 4 ++-- .gitignore | 6 +++--- README.md | 16 ++++++++-------- netlify.toml | 4 ++-- package.json | 5 +++-- packages/hugoautogen/package.json | 9 --------- 6 files changed, 18 insertions(+), 26 deletions(-) delete mode 100644 packages/hugoautogen/package.json diff --git a/.github/workflows/links.yaml b/.github/workflows/links.yaml index 88322da869a..8c50a39113a 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 install --omit=optional + - run: npm run install:all - name: Install lychee env: @@ -44,5 +44,5 @@ jobs: GITHUB_TOKEN: ${{ github.token }} run: npm run check:links - - name: Verify committed cache and generated files are unchanged + - name: Verify the committed cache is unchanged run: npm run check:generated diff --git a/.gitignore b/.gitignore index f990f9dd69f..a81c29cc766 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,6 @@ resources/ node_modules/ package-lock.json .hugo_build.lock -# Volatile staleness marker from `hugo mod npm pack` (its hash churns on any -# package.json change); the sibling package.json that npm needs stays committed. -packages/hugoautogen/hugo_packagemeta.json +# Generated by `hugo mod npm pack` (run via `npm run install:all`) and +# regenerated on every fresh checkout, so this directory is not committed. +packages/hugoautogen/ diff --git a/README.md b/README.md index 4de90855c9a..8ab066682c3 100644 --- a/README.md +++ b/README.md @@ -52,13 +52,6 @@ configuration settings do in the Once your settings are adjusted, you can edit your own versions of the site’s source files. -If you want to do SCSS edits and want to publish these, you need to install -`PostCSS` - -```bash -npm install -``` - ## Running the website locally Building and running the site locally requires a recent `extended` version of @@ -68,7 +61,14 @@ your environment in our guide. Once you've made your working copy of the site repo, from the repo root folder, -run: +first install the npm dependencies, including the Bootstrap and Font Awesome +assets that the theme sources as an npm package: + +```bash +npm run install:all +``` + +Then run: ```bash hugo server diff --git a/netlify.toml b/netlify.toml index 7898ef86a67..68ad5219ca3 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 build:preview" +command = "npm run install:all && npm run build:preview" publish = "public" [build.environment] GO_VERSION = "1.22.2" [context.production] -command = "npm run build:production" +command = "npm run install:all && npm run build:production" diff --git a/package.json b/package.json index b7bc7b1aec1..b3ae2ead1bd 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "_check:links": "npx lychee-norm-cache", "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit --allow-empty -m \"Site at $HASH\"", "_diff:check": "git diff --name-only --exit-code", - "_diff:fail": "npm run _diff:check || (echo; echo 'ERROR: committed files above changed during CI. Regenerate locally (npm run check:links; npm run update:docsy:pack) and commit.'; echo; exit 1)", + "_diff:fail": "npm run _diff:check || (echo; echo 'ERROR: committed files above changed during CI. Regenerate locally (npm run check:links) and commit.'; echo; exit 1)", "_fix:permissions": "chmod -R u+w public/* 2>/dev/null || true", "_get:docsy": "hugo mod get github.com/google/docsy/theme@v$npm_package_version", "_hugo-dev": "npm run _hugo -- -e dev --logLevel info -DFE", @@ -28,7 +28,7 @@ "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", "build:production": "npm run _hugo -- --minify", "build": "npm run _build -- ", - "check:generated": "hugo mod npm pack && npm run _diff:fail", + "check:generated": "npm run _diff:fail", "check:links:internal": "npm run _check:links -- --offline", "check:links": "npm run _check:links", "ci:prepare": "npm run _get:docsy && hugo mod graph && hugo mod tidy", @@ -37,6 +37,7 @@ "fix:format:diff": "npm run fix:format", "fix:format": "npm run _check:format -- --write", "fix": "npm run fix:format", + "install:all": "echo 'Two npm installs (not one) are needed because Hugo, itself an npm dependency, generates the packages/hugoautogen manifest in between.' && 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", diff --git a/packages/hugoautogen/package.json b/packages/hugoautogen/package.json deleted file mode 100644 index 7708b29db6b..00000000000 --- a/packages/hugoautogen/package.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "dependencies": { - "@fortawesome/fontawesome-free": "6.7.2", - "bootstrap": "5.3.8" - }, - "devDependencies": {}, - "name": "docsy-example", - "version": "0.1.0" -} From b9cd3289f35ba9a0edbfa85e2f85cb62a323847d Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 13:23:35 -0400 Subject: [PATCH 2/4] Reviewer feedback and adjustments --- .github/workflows/links.yaml | 8 +++++++- .gitignore | 2 -- README.md | 2 +- package.json | 4 +--- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/links.yaml b/.github/workflows/links.yaml index 8c50a39113a..42a8941302e 100644 --- a/.github/workflows/links.yaml +++ b/.github/workflows/links.yaml @@ -45,4 +45,10 @@ jobs: run: npm run check:links - name: Verify the committed cache is unchanged - run: npm run check:generated + run: | + npm run _diff:check || { + echo + echo 'ERROR: cache changed; regenerate locally (npm run check:links) and commit.' + echo + exit 1 + } diff --git a/.gitignore b/.gitignore index a81c29cc766..ecfc7f87e34 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,4 @@ resources/ node_modules/ package-lock.json .hugo_build.lock -# Generated by `hugo mod npm pack` (run via `npm run install:all`) and -# regenerated on every fresh checkout, so this directory is not committed. packages/hugoautogen/ diff --git a/README.md b/README.md index 8ab066682c3..dffb484ad1f 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ 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 an npm package: +assets that the theme sources as npm packages: ```bash npm run install:all diff --git a/package.json b/package.json index b3ae2ead1bd..cf15ce447bf 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,6 @@ "_check:links": "npx lychee-norm-cache", "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit --allow-empty -m \"Site at $HASH\"", "_diff:check": "git diff --name-only --exit-code", - "_diff:fail": "npm run _diff:check || (echo; echo 'ERROR: committed files above changed during CI. Regenerate locally (npm run check:links) and commit.'; echo; exit 1)", "_fix:permissions": "chmod -R u+w public/* 2>/dev/null || true", "_get:docsy": "hugo mod get github.com/google/docsy/theme@v$npm_package_version", "_hugo-dev": "npm run _hugo -- -e dev --logLevel info -DFE", @@ -28,7 +27,6 @@ "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", "build:production": "npm run _hugo -- --minify", "build": "npm run _build -- ", - "check:generated": "npm run _diff:fail", "check:links:internal": "npm run _check:links -- --offline", "check:links": "npm run _check:links", "ci:prepare": "npm run _get:docsy && hugo mod graph && hugo mod tidy", @@ -37,7 +35,7 @@ "fix:format:diff": "npm run fix:format", "fix:format": "npm run _check:format -- --write", "fix": "npm run fix:format", - "install:all": "echo 'Two npm installs (not one) are needed because Hugo, itself an npm dependency, generates the packages/hugoautogen manifest in between.' && npm install && hugo mod npm pack && npm install", + "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", From d6e50cf09211c864e33aaaa35a0e85b87cac1ae9 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 13:24:39 -0400 Subject: [PATCH 3/4] TEMP - seeded diff .lycheecache --- .lycheecache | 1 - 1 file changed, 1 deletion(-) diff --git a/.lycheecache b/.lycheecache index a7a1dba3f20..cac9e8fd830 100644 --- a/.lycheecache +++ b/.lycheecache @@ -18,7 +18,6 @@ https://example.docsy.dev/blog/,200,1782763743 https://example.docsy.dev/blog/news/,200,1782763743 https://example.docsy.dev/blog/releases/,200,1782763744 https://example.docsy.dev/community/,200,1782763743 -https://example.docsy.dev/docs/,200,1782763743 https://example.docsy.dev/docs/getting-started/,200,1782763743 https://example.docsy.dev/docs/reference/,200,1782763744 https://example.docsy.dev/docs/tasks/,200,1782763744 From d0a4c1ef808c6042e0b6eca373a1ab558f461d7d Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 1 Jul 2026 13:25:59 -0400 Subject: [PATCH 4/4] Update .lycheecache --- .lycheecache | 1 + 1 file changed, 1 insertion(+) diff --git a/.lycheecache b/.lycheecache index cac9e8fd830..0a614b2ae7f 100644 --- a/.lycheecache +++ b/.lycheecache @@ -18,6 +18,7 @@ https://example.docsy.dev/blog/,200,1782763743 https://example.docsy.dev/blog/news/,200,1782763743 https://example.docsy.dev/blog/releases/,200,1782763744 https://example.docsy.dev/community/,200,1782763743 +https://example.docsy.dev/docs/,200,1782926753 https://example.docsy.dev/docs/getting-started/,200,1782763743 https://example.docsy.dev/docs/reference/,200,1782763744 https://example.docsy.dev/docs/tasks/,200,1782763744