configs/ai/skills/docs_architecture/SKILL.md

name, description

name	description
docs_architecture	Exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Nginx Wiki infrastructure.

Docs Architecture Skill

This skill documents the exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Nginx Wiki infrastructure.

🏗️ 1. Core Architecture (Decoupled Repositories)

The system is split into three independent Git repositories hosted on git.wompmacho.com:

1. Framework (/srv/dev/hugo/wiki): Repository hugo-framework

   • Purpose: The central Hugo engine. The Blowfish theme is fully decoupled/vendored directly into the project's root folders (layouts/, assets/, static/, data/, i18n/, archetypes/). No theme submodules are used, protecting the site from upstream updates breaking the build.
   • Rule: NEVER place content (.md files) here. NEVER place environment-specific overrides (like hardcoded editURLs or top-level menus) in the global config.

2. Public Wiki (/srv/docs/public): Repository docs-public

   • Purpose: Public-facing markdown notes, assets (/static), and its own top-bar menu configuration (config/_default/menus.en.toml).
   • Deployment Target: /srv/www/docs-public
   • Live URL: https://wiki.wompmacho.com (proxied by NPM).

3. Private Wiki (/srv/docs/private): Repository docs-private

   • Purpose: Personal, private markdown notes, assets (/static), and its own top-bar menu configuration (config/_default/menus.en.toml).
   • Deployment Target: /srv/www/docs-private
   • Live URL: http://10.0.0.190:9897 (or http://private via NPM).

💻 2. Local Development ("Live Link" Automation)

When working on content, the user uses Code-Server. To see real-time updates without deploying, the framework repository uses automated symlinking and preview scripts.

• preview.sh [public|private]:
  • Creates symlinks: content -> /srv/docs/[public|private] and static -> /srv/docs/[public|private]/static.
  • Overwrites or symlinks specific config overrides (like menus.en.toml).
  • Executes run-dev.sh to start the local preview server.
  • Traps exits (Ctrl+C, normal exit) to cleanly restore standard framework defaults and remove preview symlinks automatically.
• run-dev.sh:
  • Launches the server bound to 0.0.0.0:1313 with code-server proxy parameters.
  • Passes --renderToMemory to prevent local watch loops and file write latency.

🚀 3. CI/CD Pipeline (Gitea Actions)

Both docs-public and docs-private have a .gitea/workflows/deploy.yaml action.

The Build Process

1. Checkout Content: The runner checks out the markdown content.
2. Clone Framework: The runner clones the central hugo-framework repository directly. Because the Blowfish theme is fully decoupled, there is no need for submodule initialization.
3. Inject Content: Markdown and static files are copied into the framework's workspace.
4. Inject Dynamic Menus: The config/_default/menus.en.toml is injected, automatically overriding the framework's top navigation bar for that specific site.
5. Inject Edit Links (CRITICAL RULE): The "Edit this page" link on the bottom of posts MUST NOT be configured via a params.toml override, as Hugo replaces the entire file instead of merging it, destroying the Blowfish styling.
   • Fix: It is injected dynamically via an Environment Variable right before the build command:
   • HUGO_PARAMS_ARTICLE_EDITURL="https://git.../src/branch/main" hugo --minify ...
6. Deploy: The output /public folder is copied directly to the mounted /deploy volume.

🌐 4. Web Server Routing (Nginx)

The system relies on two extremely lightweight nginx:alpine containers defined in gitea/docker-compose.yaml to serve static files. They act as file servers behind Nginx Proxy Manager (NPM).

1. Public (public_wiki - Port 9896):
   • Mounts /srv/www/docs-public as read-only.
   • NPM routes wiki.wompmacho.com to Docker Host IP on port 9896.
2. Private (private_wiki - Port 9897):
   • Mounts /srv/www/docs-private as read-only.
   • NPM routes http://private to Docker Host IP on port 9897.

🛠️ 5. Known Quirks and Formatting Rules

• Decoupled Theme: The Blowfish theme is committed directly in the main codebase. Do not use Git submodules to track the theme.
• Blowfish Homepage: If the homepage is blank, it means there are no recent posts. By default, Blowfish's home layout only lists files with type: "article" or type: "posts". For generic folders, set type: "page" and layout: "list" in _index.md.
• Frontmatter: Blowfish expects standard Hugo frontmatter (date: as a string, authors: ["Name"] as an array). MkDocs-style nested YAML is incompatible and will crash the build.
• Troubleshooting: See references/troubleshooting.md for handling theme updates, build loops, and TOC configuration.