configs/ai/skills/docs_architecture/SKILL.md

Docs Architecture Skill

This skill documents the exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Caddy 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. Contains the Blowfish theme as a submodule (themes/blowfish) and the master config/_default/params.toml.
   • Rule: NEVER place content (.md files) here. NEVER place environment-specific overrides (like hardcoded editURLs or top-level menus) in the global params.toml.

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/caddy/sites/wiki
   • 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/caddy/sites/private-wiki
   • Live URL: http://10.0.0.190:9897 (or http://private via NPM).

💻 2. Local Development ("Live Link")

When working on content, the user uses Code-Server. To see real-time updates without deploying, the hugo-framework repository uses symbolic links.

• content -> /srv/docs/public
• static -> /srv/docs/public/static

Command to start local preview: cd /srv/dev/hugo/wiki && hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/"

🚀 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 natively clones the hugo-framework (including submodules) using git clone --recurse-submodules https://git.wompmacho.com/wompmacho/hugo-framework.git.
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 "dumb" file servers behind Nginx Proxy Manager (NPM), bypassing the complex Host header validation and 0-byte security issues inherent to Caddy.

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

🛠️ 5. Known Quirks and Formatting Rules

• Submodules: Always use git submodule add -b main <url> and ensure the commit pointer is tracked. Do not copy theme files physically.
• 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.