61 lines
4.2 KiB
Markdown
61 lines
4.2 KiB
Markdown
# 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. |