---
name: docs_architecture
description: 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.