When you run a blog or website, the favicon — that small icon shown in the browser tab — is a surprisingly important part of your brand identity. While migrating from WordPress to the static site generator Hugo (PaperMod theme), I had to set up and verify the favicon from scratch, so I'm writing down the whole process here.

In particular, I'll go into detail on why checker sites like RealFaviconGenerator throw warnings or errors after you've set up your favicon, and how to deal with browser caching issues.


1. Preparing the favicon image files and the static/ folder location

In a Hugo project, everything inside the static/ folder is copied as-is to the site's root path at build time (e.g. https://ricosheaven.com/).

To generate a favicon, use a site like favicon.io or RealFaviconGenerator to produce the icon package, then place the following files directly under the static/ folder.

  • static/favicon.ico (a multi-size icon containing 16x16, 32x32, and 48x48)
  • static/favicon-16x16.png
  • static/favicon-32x32.png
  • static/apple-touch-icon.png (180x180, used for saving to the iOS home screen)
🚨 Important: Don't nest these files in a subfolder like static/images/favicon.ico. They must sit directly at the top level of static/ so they get served from the default path, /favicon.ico.

2. Adding the hugo.yaml configuration (PaperMod theme)

If you're using hugo.yaml instead of hugo.toml, register an assets: entry under the params: section, following YAML's indentation rules. 

params:
  # ... existing params settings ...

  assets:
    favicon: "/favicon.ico"
    favicon16x16: "/favicon-16x16.png"
    favicon32x32: "/favicon-32x32.png"
    apple_touch_icon: "/apple-touch-icon.png"
💡 Path tip: If you add a leading / (slash) before the file name, the PaperMod theme will build an exact absolute path when generating the <head> tags, like <link rel="icon" href="https://ricosheaven.com/favicon.ico">.

3. Tips for checking browser cache and confirming the change

Favicons are cached extremely aggressively, both inside browsers (especially Safari and Chrome) and on Google's search servers. If your old WordPress-era favicon keeps showing up, or you can't see your changes reflected, verify with the methods below.

① Access the file directly (the most reliable way)

Type https://ricosheaven.com/favicon.ico directly into the browser's address bar. If the newly registered icon image appears centered on the screen with no 404 error, your Vercel and Hugo deployment succeeded perfectly.

② Safari private browsing window

In Safari, open a private browsing window with Cmd + Shift + N, then visit the site and check the tab icon.


4. Interpreting RealFaviconGenerator errors and how to respond

Don't panic if RealFaviconGenerator, the favicon checker site, shows a "Found 3 errors and 1 warning" message.

✅ Items recognized correctly (Classic & Touch icon):
• An implicit ICO favicon is found at /favicon.ico
• ICO favicon found (16x16, 32x32, 48x48)
• The touch icon is declared / downloadable / square (180x180)

➔ Every essential favicon needed for PC browsers and smartphone access is working correctly!

Causes of the warning/error items:

  • There is no SVG favicon: This is just a warning that there's no vector SVG favicon for dark mode. As long as you have .ico and .png files, it will display fine in every browser.
  • There is no 96x96 desktop PNG favicon: This is covered by the 48x48/32x32 layers embedded inside favicon.ico, so it can be safely ignored.
  • No web app manifest: This just means there's no site.webmanifest file for PWA (Progressive Web App) support, which has no impact on running an ordinary tech blog.

5. Conclusion

When applying a favicon in the Hugo PaperMod theme, the key is to place the files at the very top level of static/ and specify the correct absolute path (/favicon.ico) in hugo.yaml.

If direct URL access shows the icon correctly, there's no need to worry about the checker tool's PWA-related recommendation warnings — you can just keep running your blog comfortably until the browser crawlers update their cache!