configs/ai/skills/docs_architecture/references/troubleshooting.md

Hugo/Blowfish Troubleshooting & Pitfalls

1. Infinite Rebuild Loops

If Hugo triggers a rebuild loop:

• Cause: Hugo watches the resources/ directory, and the generation of cached/busted assets (like admonitions.scss_...json) triggers a new rebuild event.
• Fix: Add the following to config/_default/hugo.toml:

  [watch]
    ignore = ["resources/**"]
  

• Tool Usage: If the loop persists, start the server with polling to reduce sensitivity: hugo server --poll 1s

2. Table of Contents (TOC) Issues

Blowfish manages TOC natively via params.toml. Avoid using manual [TOC] or {{< toc >}} in your Markdown unless explicitly required by a specific layout.

• Standard Setup: Ensure showTableOfContents = true is set in the [article] and [list] sections of your config/_default/params.toml.
• Custom Layouts: If TOC is rendering in the wrong place, it is likely due to an overridden layouts/_default/single.html. Revert to the native theme structure (container and prose classes) so the Blowfish partials can handle the placement.
• TOC ScrollSpy Highlighting: If the TOC fails to highlight active headings when scrolling, verify that smartTOC = true is enabled in params.toml. If it is nested inside the [article] section, ensure that the layouts/partials/toc.html checks: {{ if or .Site.Params.smartTOC .Site.Params.article.smartTOC }} to correctly resolve the nested parameter.

3. Theme Updates & Customization

• Version mismatch: When Hugo updates, theme templates often break (e.g., can't evaluate field Locale).
• Decoupled Theme Installation: The theme is fully decoupled/vendored in the root folders. If you need to update Blowfish, you will copy/vendor the new templates into layouts/ and assets into assets/, but you must review custom changes to templates such as layouts/_default/single.html and layouts/partials/toc.html to make sure custom styles and scripts (like multiple TOC elements or active highlight overrides) are preserved.