25 lines
2.0 KiB
Markdown
25 lines
2.0 KiB
Markdown
# 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.
|