# 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`:
    ```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.