README

A tool for securely cleaning Hugo caches.

Task

hugo-clean-cache is a small CLI tool that reliably removes caches and resources generated by Hugo. The tool...

• automatically detects your cache path
• respects Hugo's configuration
• works on macOS, Linux, Windows (WSL/Git Bash/Node)

The Hugo cache has three typical side effects:

Generated images (thumbnails, resizes, crops) in particular tend to remain in the cache. When replacing images, it often happens that... .

1. Hugo displays outdated images
   • the old versions continue to be used,
   • even after hugo --cleanDestinationDir, incorrect files still appear,
   • my image gallery displays "ghost images".
2. resources/_gen becomes huge and confusing
   • Hugo stores all generated assets here:
     • resources/_gen/images/
     • resources/_gen/assets/
     • This can amount to thousands of files taking up hundreds of MB.
3. Debugging becomes difficult
   • When you change CSS, SCSS, images, optimisations or sizes, Hugo sometimes does not respond immediately because it is cached.

A really clean cache reset creates clear conditions, so the script clears everything that Hugo will regenerate during the next build:

• resources/_gen (all generated assets)
• Complete public/*
• The image cache from hugo.toml, including:
  • :cacheDir
  • [caches.images]
  • macOS default ~/Library/Caches/hugo_cache
  • Fallback $TMPDIR/hugo_cache

What will be deleted?

• resources/_gen: Assets generated by Hugo (CSS, JS, images)
• public/*: Everything that Hugo regenerates with each build
• Image cache: located via hugo.toml or defaults

What will NOT be deleted?

The script does not delete any productive content,

• no Markdown files
• no themes
• no content

It only removes files that Hugo can reproduce.

Setup

npm i -D hugo-clean-cache

Then, place an hugo-clean-cache.config.json configuration file in the root directory of your project with the following settings:

• cleanResourcesGen: Deletes resources/_gen
• cleanPublic: Deletes public/* (but not the directory itself)
• cleanImageCache: Deletes the Hugo image cache (from [caches.images], or Default)
• defaultImagesCacheSubdir: Fallback subfolder: <cacheDir>/…
• extraPaths: Any additional paths, including :cacheDir/...

Example 1

{
  "hugoConfig": "hugo.toml",

  "cleanResourcesGen": true,
  "cleanPublic": true,
  "cleanImageCache": true,

  "defaultImagesCacheSubdir": "hugogridgallery",

  "extraPaths": [
    ":cacheDir/thegallery", 
    "public/pwa-cache"
  ]
}

Delete:

• resources/_gen
• public/*
• <HUGO_CACHEDIR>/hugogridgallery
• Additionally:
  • <HUGO_CACHEDIR>/thegallery
  • public/pwa-cache

Example 2

{
  "cleanResourcesGen": false,
  "cleanPublic": false,
  "cleanImageCache": true,
  "defaultImagesCacheSubdir": "thegallery"
}

Only the Hugo image cache is deleted. This is useful if publicly generated images need to be re-rendered, but public/ and resources/ should not be touched.

Example 3

Vollständig benutzerdefinierte Konfiguration

{
  "hugoConfig": "config/_default/hugo.toml",

  "cleanResourcesGen": true,
  "cleanPublic": false,
  "cleanImageCache": false,

  "extraPaths": [
    "resources/cache",
    "public/tmp",
    "/Users/cnichte/tmp/custom-cache",
    ":cacheDir/othermodule",
    ":cacheDir/gallerydeluxe"
  ]
}

What happens:

• Standard Hugo caches remain untouched
• Only your own cache locations are deleted
• Paths can be absolute or relative
• :cacheDir/<…> automatically replaces the real Hugo CacheDir

Working with build skripts

Dann in der package.json:

"scripts": {
  "clean:cache": "hugo-clean-cache",
  "clean": "find . -type f -name .DS_Store -delete && rm -rf public",
  "clean:all": "npm run clean && npm run clean:cache",
}