Finalize framework: Fix submodules and clean artifacts

README.md

@@ -0,0 +1,102 @@
+# Project: Self-Hosted CI/CD and Static Hosting (Blowfish)
+
+This project manages a centralized self-hosted environment using **Gitea** for version control and automation, **Caddy** as a lightweight web server, and **Nginx Proxy Manager** for SSL termination. The system relies on a shared host volume to move static files from the Gitea Runner to the web server directory.
+
+## 🏗️ Architecture Split
+
+To allow for seamless Dev vs. Prod workflows, the architecture is split into two repositories:
+
+1.  **Framework (`/srv/dev/hugo/wiki`)**: This repository (`hugo-framework`). Contains the Hugo engine, themes (Blowfish), layouts, and configuration.
+2.  **Content (`/srv/docs/public`)**: A separate repository (`docs-public`). Contains only the Markdown files and static assets.
+
+**Local Dev "Live Link":**
+In this `hugo-framework` repository, `content/` and `static/` are **symbolic links** pointing to `/srv/docs/public`. This allows for real-time local previews of your notes when running `hugo server`.
+
+## 🚀 CI/CD Pipeline
+
+Deployment is fully automated through Gitea Actions.
+
+1.  **Trigger:** Push a commit to the `main` branch of the `docs-public` repository.
+2.  **Runner Execution:** The Gitea Runner mounts the `hugo-framework` directory and executes the build steps.
+3.  **Sync:** The Runner uses a volume mount (`/srv/caddy/sites:/deploy`) to copy the generated `public/` folder directly to the host's web server directory.
+
+---
+
+## 💻 Local Development
+
+1.  **Work in the Docs folder**: Edit your markdown files in `/srv/docs/public/`.
+2.  **Asset Management:** Place any files for download (PDFs, images) in the `/srv/docs/public/static/` directory.
+3.  **Preview changes (Code-Server)**: 
+    ```bash
+    cd /srv/dev/hugo/wiki
+    alias hugo-rebuild='rm -rf public/ && hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/" --ignoreCache'
+    hugo-rebuild
+    ```
+4.  **Deploy**: 
+    ```bash
+    cd /srv/docs/public
+    git add .
+    git commit -m "Your note update"
+    git push origin main
+    ```
+
+---
+
+## 🛠️ Hugo Fresh Installation Notes
+
+To rebuild this environment—especially for a project like **Blowfish**—you need more than just the binary; you need the extended capabilities for CSS processing.
+
+### Prerequisites
+
+- **Hugo (Extended Version)**: Required for SCSS/PostCSS processing.
+- **Node.js** & **npm**: Required for managing the theme's dependencies.
+- **npx**: Comes with npm; used to run build-time tools for Blowfish.
+
+```bash
+# Install nvm script and updating bashrc
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+```
+
+### 1. Installation (The "Extended" Way)
+
+* **Linux/Ubuntu:** Use the `.deb` package from the [Hugo GitHub releases](https://github.com/gohugoio/hugo/releases).
+
+    ```bash
+    wget https://github.com/gohugoio/hugo/releases/download/v0.140.0/hugo_extended_0.140.0_linux-amd64.deb
+    sudo dpkg -i hugo_extended_0.140.0_linux-amd64.deb
+    ```
+* **Verify:** Ensure you have the extended version: `hugo version` (it should explicitly say `+extended`).
+
+### 2. Initialize the Framework
+
+If you are cloning this `hugo-framework` repository fresh:
+
+1.  **Clone the Repo**:
+    ```bash
+    git clone https://git.wompmacho.com/wompmacho/hugo-framework.git my-wiki
+    cd my-wiki
+    ```
+2.  **Pull Submodules** (The Blowfish theme):
+    ```bash
+    git submodule update --init --recursive
+    ```
+3.  **Install Node Dependencies**:
+    ```bash
+    npm install
+    ```
+4.  **Establish Symlinks** (Point to your content repo):
+    ```bash
+    rm -rf content static
+    ln -s /path/to/docs-public/content ./content
+    ln -s /path/to/docs-public/static ./static
+    ```
+
+### 3. Critical Blowfish Configuration Note
+
+To prevent common theme breakage during a fresh setup, you must initialize the configuration files correctly:
+
+- Copy the config directory from `themes/blowfish/config/_default/` to your project's `config/` directory.
+- Ensure your `hugo.toml` (or `config.toml`) correctly references the Blowfish theme.
+- If the site is blank, run `npx postcss` or ensure your `package.json` has the correct scripts to compile SCSS, as Hugo cannot process Blowfish's advanced CSS/JS requirements without these tools.
+
+For full theme documentation, visit: https://blowfish.page/docs/