hugo/zeon-studio.hugoplate
1
0
Fork 0
mirror of https://github.com/zeon-studio/hugoplate.git synced 2026-09-10 07:06:19 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity
zeon-studio.hugoplate/.agents/skills/hugo-template-guidance/references/hugo-modules.md

2.5 KiB
Raw Blame History

Adding or Removing Hugo Modules

Hugo Modules (https://github.com/gethugothemes/hugo-modules) provide most non-trivial functionality — search, SEO, images, PWA, accordions/tabs/modals, shortcodes, announcement bar, analytics, etc. Each is a separate Go module declared as an [[imports]] block in config/_default/module.toml.

Enable a module

  1. In config/_default/module.toml, either uncomment an existing # [[imports]] / # path = "..." pair, or add a new block:

    [[imports]]
path = "github.com/gethugothemes/hugo-modules/<module-name>"

    Module names are paths under github.com/gethugothemes/hugo-modules/ (e.g. search, pwa, icons/themify-icons, seo-tools/plausible-analytics, components/crisp-chat).

  2. Run pnpm update-modules to fetch the module and rewrite go.mod/go.sum.

  3. Restart the dev server (npx kill-port 1313 -y && pnpm dev).

  4. Use the partials/shortcodes/config the module adds — check the module's source (URL is the path value) for its partial names, shortcode names, and any params/config block it expects in config/_default/params.toml or similar and what kind of data it expects accoding to its docs (e.g. images module's image partial expects a dict with Src, Alt, Loading, Class, and DisplayXL keys).

Disable or delete a module

  1. Delete or comment out its [[imports]] block in config/_default/module.toml.
  2. Remove anything in the site that depends on it — partial/partialCached calls, shortcodes used in content, and any related config block (e.g. [search] in params.toml). Leaving these in place causes build errors ("partial not found") once the module is gone.
  3. Run pnpm update-modules.
  4. Restart the dev server.

Currently available but disabled (commented out in module.toml)

icons/themify-icons, components/valine-comment, components/crisp-chat, seo-tools/baidu-analytics, seo-tools/matomo-analytics, seo-tools/plausible-analytics, seo-tools/counter-analytics — uncomment + pnpm update-modules to enable.

DO NOT

  • Hand-edit go.mod / go.sum — they're regenerated by pnpm update-modules.
  • Edit a module's files under the Go module cache or themes/<theme>/ — modules are read-only dependencies; override their partials via root layouts/_partials/ instead (see references/component-usage.md).
  • Remove an [[imports]] block while partials/shortcodes from that module are still referenced — fix or remove those usages first.