Root-home the hugo-extended pin, adopt a two-step update flow, open Renovate managers

.vscode/cspell.json

@@ -59,6 +59,7 @@
     "prereqs",
     "quang",
     "readfile",
+    "redoc",
     "refcache",
     "relref",
     "scrollspy",

docsy.dev/.lycheecache

@@ -598,6 +598,7 @@ https://github.com/in-toto/in-toto.io/issues/76,200,1782498236
 https://github.com/jaegertracing/documentation/issues/746,200,1782498237
 https://github.com/jakejarvis/hugo-extended,200,1782563370
 https://github.com/jakejarvis/hugo-extended/issues/183,200,1782498234
+https://github.com/jakejarvis/hugo-extended/releases,200,1787794573
 https://github.com/jgraph/docker-drawio/blob/master/README.md,200,1782498242
 https://github.com/jmooring,200,1782498238
 https://github.com/jmooring/hvm,200,1782498231

docsy.dev/content/en/docs/content/adding-content.md

@@ -240,9 +240,8 @@ The minimum front matter you need to provide is a title: everything else is up
 to you! However, if you leave out the page weight, your
 [navigation](/docs/content/navigation) may get a little disorganized. You may
 also want to include `description` since Docsy uses that to generate the meta
-`description` tag used by search engines. See [Search Engine Optimization (SEO)
-meta tags]({{< ref "feedback#search-engine-optimization-meta-tags" >}}) for
-details.
+`description` tag used by search engines. For details, see
+[Search Engine Optimization (SEO) meta tags](/docs/content/feedback/#search-engine-optimization-meta-tags).
 
 ## Page content
 

docsy.dev/content/en/project/about/changelog.md

@@ -1,6 +1,6 @@
 ---
 title: Changelog
-description: Docsy repository changelog
+description: Breaking changes and release highlights, per release
 aliases: [../changelog]
 # prettier-ignore
 cSpell:ignore: deining FOUC gitmodules gtag lookandfeel mhchem navs notoc tabpane onedark shurup
@@ -112,7 +112,7 @@ Specifically, the Docsy team **officially supports** the following:
 
 - The tool versions as specified for the Docsy release you are using:
   - **Hugo**:
-    - The version pinned as `hugo-extended` in [docsy.dev/package.json][]
+    - The version pinned as `hugo-extended` in [package.json][]
       ({{% hugo-version %}})
     - Older versions, down to Docsy's declared [minimum Hugo version][], usually
       work.
@@ -125,7 +125,6 @@ Everything else — including Windows — is supported on a best-effort basis.
 
 <!-- prettier-ignore-start -->
 [@docsy/theme]: https://www.npmjs.com/package/@docsy/theme
-[docsy.dev/package.json]: https://github.com/google/docsy/blob/main/docsy.dev/package.json
 [minimum Hugo version]: /docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo
 [package.json]: https://github.com/google/docsy/blob/main/package.json
 <!-- prettier-ignore-end -->

docsy.dev/content/en/project/about/maintainer-notes.md

@@ -1,6 +1,6 @@
 ---
 title: Maintainer notes
-description: Notes for Docsy maintainers
+description: Release, dependency-update, and Hugo-support procedures
 aliases: [contributing, ../contributing]
 cSpell:ignore: hugo creatordate lycheecache opentelemetry prebuild worktree
 ---
@@ -116,13 +116,27 @@ with Hugo pinned to the declared minimum, run [test:smoke](#test-suites).
 ### Officially supported Hugo version {#official-hugo-version}
 
 The Hugo version that Docsy [officially supports][] is pinned as the
-`hugo-extended` dev dependency in [docsy.dev/package.json][].
-
-This version is generally kept in sync with the latest Hugo release; to update
-it, run:
-
-- `npm -C docsy.dev run update:hugo` for the latest
-- `npm -C docsy.dev install -DE hugo-extended@X.Y.Z` for a specific version
+`hugo-extended` dev dependency in the root [package.json][].
+
+This version is generally kept in sync with the latest Hugo release. Updating it
+is a two-step flow, run from the repo root:
+
+1. Review the target [hugo-extended][] release (usually the newest), then run
+   `npm run update:hugo -- X.Y.Z`: bumps the pin script-free (the exact,
+   reviewed **stable** version only).
+2. Run `npm run approve:hugo`: syncs the tree to the lock (script-free),
+   approves the new version's install script, re-runs the supply-chain audit --
+   which flags any root-`overrides` drift the bump caused (npm applies overrides
+   only while re-resolving) **before** the newly approved installer executes --
+   then rebuilds the package so the `hugo` binary lands. The approval gates the
+   install script only (the hugo binary self-installs at first use), so don't
+   run builds between the two steps. Script-enabled installs, CI's
+   `install:safe` included, fail until the new version is approved.
+
+Automated version updates don't bump hugo-extended: the
+[Renovate config](#dependency-updates) disables them. Security updates (Renovate
+vulnerability alerts, GitHub's config-free Dependabot) can still bump it; such a
+PR fails CI until the bump is approved (step 2 above).
 
 Docs render this version live through the `hugo-version` shortcode
 (`hugo.Version`): docsy.dev builds always run the pinned Hugo.
@@ -142,14 +156,14 @@ layouts for now: the default base template renders scripts through an unkeyed
 registry][npm-registry] and [OSV][] for advisories affecting the target version.
 Verify that a page using the dependency (the diagrams and formulae page, for
 example) renders with the new pin. Renovate proposes routine bumps (see
-`renovate.json5`), subject to a minimum release age. When bumping `katex`, note
-that the pinned assets style markup generated by Hugo's embedded KaTeX engine:
-check the KaTeX version that the
+[Dependency updates](#dependency-updates)), subject to a minimum release age.
+When bumping `katex`, note that the pinned assets style markup generated by
+Hugo's embedded KaTeX engine: check the KaTeX version that the
 [transform.ToMath docs](https://gohugo.io/functions/transform/tomath/) pair with
 the current Hugo, and verify a math-bearing page renders cleanly. A `redoc` bump
-to 3.x is a manual migration: Redoc 3 moves the CDN script from
-`bundles/redoc.standalone.js` to `bundle/redoc.js`, so the shortcode's URL must
-change with it (Renovate is capped at `<3`).
+to 3.x needs more than the version line: Redoc 3 moves the CDN script from
+`bundles/redoc.standalone.js` to `bundle/redoc.js`, so when Renovate proposes
+3.x, the `redoc` shortcode's URL change is part of that review.
 
 An emergency security bump (an advisory landing between releases) is a manual
 edit to the same line, made directly on a `release` branch and shipped through
@@ -161,6 +175,34 @@ regular release; it explicitly bypasses Renovate's minimum release-age gate.
 [diagrams]: /docs/content/diagrams-and-formulae/
 <!-- prettier-ignore-end -->
 
+## Dependency updates
+
+Automated updates are configured through Renovate. Settings rationale:
+
+- `ignorePresets`: the preset's 3-day npm cooldown would override this repo's
+  7-day `minimumReleaseAge`. Caution: this exclusion silently stops working if
+  the preset is renamed upstream. The preset's age exemptions for update types
+  without release timestamps (pin, replacement, rollback) are deliberately not
+  restored: such PRs never satisfy the age check and need manual age validation
+  at review.
+- `lockFileMaintenance` off: wholesale lock re-resolves would churn the
+  committed lockfiles; transitive security fixes arrive alert-driven instead.
+- Package rules:
+  - `hugo-extended` updates are [carefully chosen](#official-hugo-version) at
+    Docsy release time.
+  - Bootstrap and Font Awesome are updated deliberately via
+    `npm run update:theme-dep -- PKG X.Y.Z` (declared dependencies only, exact
+    stable versions; the chain restores `theme/node_modules`, which a
+    workspace-targeted install prunes, and ends with the ScrollSpy-patch
+    reminder).
+  - The custom manager updates the [script-dependency pins](#script-versions) in
+    `theme/hugo.yaml`. All other detected managers are active, including npm and
+    GitHub Actions (SHA-digest pins).
+
+Renovate's vulnerability-alert PRs stay on (immediate, cooldown-exempt), beside
+GitHub's config-free Dependabot security updates; a rare duplicate PR is
+accepted.
+
 ## Test suites
 
 From the repo root:
@@ -807,8 +849,8 @@ To test a Docsy branch or release from a consumer site, for each site:
 
 ## Release helper scripts
 
-- NPM scripts: `set:version` and `set:version:*`; `update:hugo` (see
-  [Hugo versions](#hugo-versions))
+- NPM scripts: `set:version` and `set:version:*`; `update:hugo`,
+  `update:theme-dep`, and `approve:hugo` (see [Hugo versions](#hugo-versions))
 - `scripts/get-build-id.sh`: Builds `X.Y.Z-dev+…-over-main-…` from the latest
   semver tag on `main`, commit offset, and tip SHA; if **`package.json`**’s
   X.Y.Z core is already **greater** than that git-derived core, keeps the higher
@@ -833,11 +875,11 @@ To test a Docsy branch or release from a consumer site, for each site:
 [docsy.dev]: <{{% _param baseURL %}}>
 [docsy.dev/config]: <{{% param github_repo %}}/blob/main/docsy.dev/config/>
 [docsy.dev/config/_default/hugo.yaml]: <{{% param github_repo %}}/blob/main/docsy.dev/config/_default/hugo.yaml>
-[docsy.dev/package.json]: <{{% param github_repo %}}/blob/main/docsy.dev/package.json>
 [Draft a new release]: <{{% param github_repo %}}/releases/new>
 [Examples page]: /examples/
 [github.com/google/docsy/theme]: <{{% param github_repo %}}/blob/main/theme/>
 [go.mod]: <{{% param github_repo %}}/blob/main/theme/go.mod>
+[hugo-extended]: https://github.com/jakejarvis/hugo-extended/releases
 [milestones]: <{{% param github_repo %}}/milestones>
 [officially supports]: /project/about/changelog/#official-support
 [opentelemetry.io]: https://github.com/open-telemetry/opentelemetry.io

docsy.dev/package.json

@@ -38,18 +38,15 @@
     "test:hugo-build": "node --test 'tests/hugo-build/**/*.test.mjs'",
     "test:md-output": "node --test 'tests/md-output/**/*.test.mjs'",
     "test": "npm run seq -- test:base test:extra",
-    "update:dep": "npm run -s update:hugo",
     "update:favicon-goldens": "node tests/favicons/update-goldens.mjs",
     "update:goldens": "npm run build && npm run _update:goldens",
-    "update:hugo": "npm install --save-exact -D hugo-extended@latest",
     "update:md-goldens": "node tests/md-output/update-goldens.mjs",
     "update:packages": "npm-check-updates -u"
   },
   "dependencies-note": "Dependencies installed from ../theme; see the root install:theme-deps script",
   "devDependencies": {
     "afdocs": "^0.19.0",
     "cross-env": "^10.1.0",
-    "hugo-extended": "0.164.0",
     "link-cache": "^0.3.0",
     "npm-check-updates": "^19.6.3",
     "rtlcss": "^4.3.0"

package.json

@@ -30,6 +30,7 @@
     "_cp:bs-scrollspy": "perl scripts/scrollspy-patch/extract-method.pl",
     "_gen-chroma-styles": "bash -c scripts/gen-chroma-styles.sh",
     "_install:safe:post": "node scripts/rebuild-hugo-extended.mjs && npm run install:theme-deps",
+    "_install:safe:pre": "npm ci --ignore-scripts --no-audit --no-fund",
     "_netlify:prepare": "npm run -s is:clean && npm run install:safe && npm run -s is:clean && npm run -s _netlify:set-build-id",
     "_netlify:set-build-id": "test -n \"$COMMIT_REF\" || { echo 'COMMIT_REF is not set' >&2; exit 1; } && npm run -s set:version -- --id \"$(echo \"$COMMIT_REF\" | cut -c1-8)\"",
     "_clean:node_modules": "bash -c 'rm -rf {.,docsy.dev,theme}/{resources,node_modules}'",
@@ -39,9 +40,12 @@
     "_serve": "npm run -C docsy.dev _serve --",
     "_spv:example": "echo TBC - npm run -s __spv docsy.dev/config/example/params.yaml --",
     "_spv": "npm run -s __spv docsy.dev/config/*/params.yaml --",
+    "_sync:theme-lock": "npm install --prefix theme --package-lock-only --ignore-scripts",
     "_test:fix-clean": "npm run fix-for-test && npm run -s is:clean",
     "_test:full:common": "npm run _test:fix-clean && npm run test:repo",
     "_test:full:pre": "npm run _prepare && npm run -s is:clean",
+    "_test:supply-chain": "node --test tests/supply-chain-audit.test.mjs",
+    "approve:hugo": "npm run _install:safe:pre && npm approve-scripts --allow-scripts-pin hugo-extended && npm run -s _test:supply-chain && npm run _install:safe:post",
     "build": "npm run -C docsy.dev build --",
     "check:afdocs:dev": "npm run -s _check:afdocs -- http://localhost:1313 | awk '/./{if(s)printf \"%s\",b; b=\"\"; print; s=1; next} s{b=b RS}' | tee docsy.dev/content/en/docs/content/agent-support/afdocs-scorecard.txt",
     "check:format": "npm list prettier && npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
@@ -57,7 +61,7 @@
     "fix:refcache": "npm run -C docsy.dev fix:refcache",
     "fix": "npm run fix:format && npm run fix:markdown && npm run -C docsy.dev fix",
     "hugo": "hugo",
-    "install:safe": "npm ci --ignore-scripts --no-audit --no-fund && npm run _install:safe:post",
+    "install:safe": "npm run _install:safe:pre && npm run _install:safe:post",
     "install:theme-deps": "npm ci --prefix theme --ignore-scripts --omit=dev --omit=peer --no-audit --no-fund",
     "install:browser": "node node_modules/puppeteer/install.mjs",
     "is:clean": "bash -c 'o=$(git status --porcelain -uall); echo \"$o\"; [ -z \"$o\" ]'",
@@ -76,12 +80,12 @@
     "test:website": "npm run -C docsy.dev test",
     "test": "npm run fix-and-test",
     "update::post": "echo; echo 'IMPORTANT! Run the following in case the ScrollSpy patch needs to be updated:\n  npm run _prepare'; echo",
-    "update:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest && npm run -s update::post",
     "update:goldens": "npm run -C docsy.dev update:goldens && npm run update:markup-goldens",
+    "update:hugo": "node scripts/update-dep.mjs hugo-extended -D",
     "update:markup-goldens": "node tests/fixture-site/update-markup-goldens.mjs",
     "update:packages:all": "npm run update:packages --workspaces --include-workspace-root",
-    "update:packages:not-hugo": "npm run update:packages -- -x hugo-extended",
-    "update:packages": "bash -c 'npm-check-updates -u \"$@\" && npm run -s update::post' -",
+    "update:packages": "bash -c 'npm-check-updates -u -x hugo-extended \"$@\" && npm run -s update::post' -",
+    "update:theme-dep": "bash -c 'node scripts/update-dep.mjs \"$1\" --workspace=theme \"$2\" && npm run -s _sync:theme-lock && npm run -s install:theme-deps && npm run -s update::post' -",
     "update:visual-goldens": "UPDATE_VISUAL_GOLDENS=1 npm run test:visual",
     "update:visual-goldens:linux": "node tests/visual/update-goldens-linux.mjs",
     "wt": "HUGO_THEME=$(basename \"$PWD\")/theme npm run",
@@ -90,6 +94,7 @@
   "devDependencies": {
     "@cspell/dict-fr-fr": "^2.3.2",
     "@pchalin/markdownlint-rule-link-pattern": "^0.3.0",
+    "hugo-extended": "0.164.0",
     "jsdom": "^29.1.1",
     "markdownlint-cli2": "^0.23.2",
     "markdownlint-rule-no-shortcut-ref-link": "^0.3.1",
@@ -110,7 +115,7 @@
   "spelling": "cSpell:ignore uall -",
   "allowScripts": {
     "@parcel/watcher": false,
-    "hugo-extended@0.164.0": true,
-    "puppeteer": false
+    "puppeteer": false,
+    "hugo-extended@0.164.0": true
   }
 }

renovate.json5

@@ -1,37 +1,22 @@
 {
   $schema: 'https://docs.renovatebot.com/renovate-schema.json',
   extends: ['config:best-practices'],
-  // config:best-practices pulls in security:minimumReleaseAgeNpm: its 3-day npm
-  // rule would override the global minimumReleaseAge below. Its age exemptions
-  // for update types without release timestamps (pin, replacement, rollback,
-  // among others) are deliberately not restored: such PRs never satisfy the age
-  // check and need manual age validation at review, as they already do for
-  // every other datasource.
-  //
-  // IMPORTANT: an upstream rename of the preset silently re-admits it.
+  // For details about this repo's settings, see
+  // https://www.docsy.dev/project/about/maintainer-notes/#dependency-updates
   ignorePresets: ['security:minimumReleaseAgeNpm'],
-  timezone: 'America/Toronto',
-  schedule: ['before 6am on monday'],
+  lockFileMaintenance: { enabled: false },
+  schedule: ['* * * * 0'], // Sunday (UTC)
   labels: ['dependencies'],
-  enabledManagers: ['custom.jsonata'],
-  // Deliberately datasource-wide: applies to the pins below and to every
-  // datasource this config may grow to manage. Security updates keep Renovate's
-  // documented bypass of the age check.
   minimumReleaseAge: '7 days',
-  internalChecksFilter: 'strict',
   packageRules: [
     {
-      // hugo-extended is intentionally pinned; updated manually via
-      // `npm run update:hugo`.
       matchPackageNames: ['hugo-extended'],
       enabled: false,
     },
     {
-      // Redoc 3 moves the script to bundle/redoc.js (2.x:
-      // bundles/redoc.standalone.js); the redoc shortcode hardcodes the 2.x
-      // path, so a 3.x bump is a manual migration.
-      matchPackageNames: ['redoc'],
-      allowedVersions: '<3',
+      // Updated deliberately via update:theme-dep.
+      matchPackageNames: ['bootstrap', '@fortawesome/fontawesome-free'],
+      enabled: false,
     },
   ],
   customManagers: [
@@ -49,4 +34,5 @@
       datasourceTemplate: 'npm',
     },
   ],
+  // cSpell:ignore datasource jsonata
 }