CONTRIBUTING.md

How to Contribute

See the contribution guidelines.

Maintainer notes

Merge requirements and workflow security analysis are project-wide (this repo's main ruleset mirrors Docsy's).

Dependency updates

For the Renovate settings shared with Docsy and their rationale, the action-pin requirements, and the action-bump merge checks, see Docsy's Dependency updates. What differs here:

• The gomod manager is disabled; Docsy is updated manually.
• hugo-extended tracks Docsy's version rather than the latest release; see Update Hugo.
• packages/hugoautogen is regenerated from the theme, reverting any direct Bootstrap or Font Awesome bump. If a security PR bumps them directly, route the fix through a Docsy update.
• No audit test guards the action-pin comments here; the PR reviewer checks them.

Deploy logs

The site deploys on Netlify: logs are in the project's Netlify dashboard and an alternate dashboard.

Lockfile and generated manifest

The lockfile (package-lock.json) and the generated theme-dependency manifest (packages/hugoautogen/package.json) are committed so that installs are reproducible: npm run install:safe (npm ci --ignore-scripts) installs exactly what they pin.

Both files are regenerated by npm run update:docsy:pack, which, unlike install:safe, needs go at run time (hugo mod); it also normalizes the generated package's name, otherwise derived from the checkout-directory name. The Docsy-update scripts and approve:hugo run it as their post phase, and CI reruns it to catch drift. If a theme update changes either file, commit the result. The manifests declare no lifecycle hooks (guarded by tests/npm-scripts.test.mjs), so installs run no root-package code. A plain npm install resolves and may rewrite the lock.

Install configuration

.npmrc follows Docsy's, with two exceptions:

• No @docsy:registry pin: this repo publishes no packages.
• No ignore-scripts=true: the allowScripts check in Update Hugo runs only on an install that runs scripts, and this repo needs one to exist.
  • Here, CI's npm ci is that install, and so is a plain npm install unless a user-level ignore-scripts is set; either runs hugo-extended's installer. npm run install:safe runs no scripts, so unlike in Docsy's flow it never fails on a missing approval.
  • Docsy can set the key because its install:safe re-enables scripts for hugo-extended alone, in a rebuild step (officially supported version), so its CI still evaluates the allowlist; this repo's install:safe has no such step.
  • With the key set, a lock-synced hugo-extended bump with no approval would arrive with a green check-links.
  • The Netlify build is script-free (install:safe) and then runs hugo, whose wrapper self-installs the pinned binary: that path checks no approval here (Docsy's does, through its rebuild step).

Upgrade Docsy

Update Docsy to the latest tagged release:

npm run update:docsy:mod

Or update to the latest commit on the main branch:

npm run update:docsy:main

Update Hugo

hugo-extended's installer downloads and executes a binary. Every pinned version has a maintainer approval on record (allowScripts), and CI flags a bump without one: npm ci fails (Install configuration names the installs that run scripts). The approval covers the install script only; the binary self-installs at first use regardless. The two-step flow that keeps the approval current is Docsy's. What differs here:

• The version tracks Docsy's officially supported version. If a security PR bumps it, take the fix through Docsy instead: once Docsy pins a version carrying it, update to that version with the command below, then approve.
• Update using npm install --save-dev --save-exact --ignore-scripts [email protected]; this repo has no update:hugo script. For a release younger than the npm cooldown, add Docsy's NPM_CONFIG_MIN_RELEASE_AGE override to that command.
• npm run approve:hugo has no audit to re-run and no rebuild step; instead its tail regenerates the manifest (Lockfile and generated manifest), and the hugo call in that step self-installs the just-approved binary.

Develop against a local Docsy

With Docsy in the sibling folder of this repo's root (as declared in the docsy.work Hugo workspace file), prepend local to the npm script you want to invoke, e.g.:

npm run local -- serve

The local prefix runs the script against the sibling Docsy, and the server watches it, so theme edits hot-reload.

Built-site snapshot

To diff each build against the last (the A/B diff step of Docsy's consumer-site test procedure), keep the built site in a git repo and commit it after each build with npm run _commit:public. Two layouts:

• npm run make:public makes public/ itself a repo, inside the project; it needs no configuration.
• Maintainers keep public as a symlink to a sibling repo, docsy-example.g, so that the primary clone and its task worktrees (wt/docsy-example/TASK, beside the clone) share one snapshot. Hugo's Node permission model rejects a symlink whose target isn't in security.node.permissions.allowRead, so hugo.yaml lists the snapshot as seen from the clone (../docsy-example.g) and from a worktree (../../../docsy-example.g), plus . (the npm workspace link under node_modules/@docsy resolves into the project and needs it). PostCSS, run for the RTL stylesheet, is the tool that trips the check. From a worktree, the entry is live whether or not public is a symlink; an entry whose path doesn't exist is inert. A snapshot kept elsewhere needs its own entry.

Link checking

For the link cache (the committed link-cache.jsonc, its fields, and the refresh, prune, and seed recipes), see Docsy's Link checking and the link cache. What differs here:

• The cache and lychee.toml are at the repo root, and CI runs the check in .github/workflows/links.yaml.
• No refresh workflow: a lapsed seed keeps serving until you prune by hand. Run npm run link-cache -- -p 0 (drops only lapsed entries; -p N also drops the N oldest without expires), then npm run fix:link-cache to re-verify those URLs, and commit the cache.