From d9e25cd68c9409f7034cb9350233e2346c12daab Mon Sep 17 00:00:00 2001 From: wompmacho Date: Sat, 6 Jun 2026 20:18:15 +0000 Subject: [PATCH] update skill for new docs achitecture --- ai/skills/docs_architecture/SKILL.md | 44 +++++++++++++++++----------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/ai/skills/docs_architecture/SKILL.md b/ai/skills/docs_architecture/SKILL.md index 9f04631..001d0e2 100644 --- a/ai/skills/docs_architecture/SKILL.md +++ b/ai/skills/docs_architecture/SKILL.md @@ -1,33 +1,42 @@ +--- +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/Caddy Wiki infrastructure. +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. 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`. + * **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/caddy/sites/wiki` + * **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/caddy/sites/private-wiki` + * **Deployment Target**: `/srv/www/docs-private` * **Live URL**: `http://10.0.0.190:9897` (or `http://private` via NPM). -## 💻 2. Local Development ("Live Link") +## 💻 2. Local Development ("Live Link" Automation) -When working on content, the user uses **Code-Server**. To see real-time updates without deploying, the `hugo-framework` repository uses symbolic links. +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. -* `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="/"` +* **`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) @@ -35,7 +44,7 @@ Both `docs-public` and `docs-private` have a `.gitea/workflows/deploy.yaml` acti ### 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`. +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. @@ -45,17 +54,18 @@ Both `docs-public` and `docs-private` have a `.gitea/workflows/deploy.yaml` acti ## 🌐 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. +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/caddy/sites/wiki` as read-only. + * 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/caddy/sites/private-wiki` as read-only. + * 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 -* **Submodules**: Always use `git submodule add -b main ` and ensure the commit pointer is tracked. Do not copy theme files physically. +* **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. \ No newline at end of file +* **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. \ No newline at end of file