diff --git a/ai/skills/docs_architecture/references/troubleshooting.md b/ai/skills/docs_architecture/references/troubleshooting.md new file mode 100644 index 0000000..b05274d --- /dev/null +++ b/ai/skills/docs_architecture/references/troubleshooting.md @@ -0,0 +1,24 @@ +# 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. diff --git a/ai/skills/workflow_management/SKILL.md b/ai/skills/workflow_management/SKILL.md index 5920b0d..69dd5f4 100644 --- a/ai/skills/workflow_management/SKILL.md +++ b/ai/skills/workflow_management/SKILL.md @@ -23,3 +23,12 @@ This skill allows Gemini to efficiently manage the lifecycle of project workflow - **Action Items**: - [ ] [Specific task] - **Verification**: [Public-domain method to verify success] + +--- + +## Pitfalls & Best Practices + +- **Avoid Absolute Positioning in Layouts**: When customizing themes, prefer Flexbox or Grid over `position: absolute` for structural elements like Sidebars or TOCs to prevent content overlap and preserve responsive layout integrity. +- **Global Theme Settings**: For TOC rendering in Blowfish, rely on `params.toml` configuration (`showTableOfContents = true`) rather than custom Markdown shortcodes (`[TOC]` or `{{< toc >}}`), which are often theme-incompatible. +- **Custom CSS vs Theme Overrides**: Always use `assets/css/custom.css` for structural overrides. Never modify theme-internal files (`themes/blowfish/...`), as they will be overwritten during updates. +- **Container Widths**: When overriding container widths, use relative units (percentages) and `!important` sparingly to avoid breaking theme-defined responsive breakpoints. diff --git a/docker_compose/homelabel/docker-compose.yaml b/docker_compose/homelabel/docker-compose.yaml index 28f737c..57e0e14 100644 --- a/docker_compose/homelabel/docker-compose.yaml +++ b/docker_compose/homelabel/docker-compose.yaml @@ -41,12 +41,12 @@ - backend labels: # Nginx Proxy Manager Automation - - "npm.proxy.domains=homelable" + - "npm.proxy.domains=homelable.wompmacho.com" - "npm.proxy.host=${DOCKER_HOST_IP}" - "npm.proxy.port=${HOMELABEL_FRONT_PORT}" - "npm.proxy.scheme=http" - #- "npm.proxy.websockets=true" + - "npm.proxy.websockets=true" #- "npm.proxy.ssl_verify=false" - #- "npm.proxy.ssl.force=true" - #- "npm.proxy.ssl.certificate.id=1" - - "pihole.custom-record=[[\"homelable\", \"${DOCKER_HOST_IP}\"]]" \ No newline at end of file + - "npm.proxy.ssl.force=true" + - "npm.proxy.ssl.certificate.id=2" + - "pihole.custom-record=[[\"homelable.wompmacho.com\", \"${DOCKER_HOST_IP}\"]]" \ No newline at end of file diff --git a/docker_compose/homepage/config/services.yaml b/docker_compose/homepage/config/services.yaml index 8ce5f18..8040292 100644 --- a/docker_compose/homepage/config/services.yaml +++ b/docker_compose/homepage/config/services.yaml @@ -265,6 +265,6 @@ description: neko browser - homelable: icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/homelable.svg - href: "http://homelable/view?key=live" + href: "https://homelable.wompmacho.com/view?key=live" target: _self description: homelable \ No newline at end of file diff --git a/docker_compose/openai/docker-compose.yaml b/docker_compose/openai/docker-compose.yaml index 1b6b092..0a3be9c 100644 --- a/docker_compose/openai/docker-compose.yaml +++ b/docker_compose/openai/docker-compose.yaml @@ -1,6 +1,6 @@ # Open WebUI - https://docs.openwebui.com/getting-started/quick-start/ services: - openwebui: + openai: container_name: openai image: ghcr.io/open-webui/open-webui:latest restart: unless-stopped