From 077aa4b523d40e821f521fd013f59564a882d67b Mon Sep 17 00:00:00 2001 From: wompmacho Date: Wed, 25 Mar 2026 03:54:30 +0000 Subject: [PATCH] updates to wiki for architecture changes --- README.md | 123 ++++++++++++++---------------------------------------- 1 file changed, 31 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 18fbed9..1f624f0 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,41 @@ -# Project: Self-Hosted CI/CD and Static Hosting (Blowfish) +# Project: Hugo Documentation Framework (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. +This repository manages the **Hugo build environment** (config, themes, and layouts) for both the Public and Private Wikis. -## 🏗️ Architecture Split +## 🏗️ Architecture -To allow for seamless Dev vs. Prod workflows, the architecture is split into two repositories: +To allow for seamless Dev vs. Prod workflows, the architecture is split into three 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. +1. **Framework (`/srv/dev/hugo/wiki`)**: This repository (`hugo-framework`). Contains the Hugo engine, themes (Blowfish), and the **default configuration**. +2. **Public Content (`/srv/docs/public`)**: A separate repository (`docs-public`). +3. **Private Content (`/srv/docs/private`)**: A separate repository (`docs-private`). -**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`. +**Dynamic Configuration Merging:** +The Framework defines the base styling in `config/_default/params.toml`. +However, the Content repositories can dynamically override: +* **Menus**: By providing a `config/_default/menus.en.toml` file. +* **Theme Settings (Edit Links)**: Injected via Environment Variables (`HUGO_PARAMS_ARTICLE_EDITURL`) during the CI/CD pipeline to avoid destroying the framework's default arrays. + +## 💻 Local Development ("Live Link") + +To write documentation with real-time previews, you use symbolic links on your host machine: + +1. **Establish Symlinks**: + ```bash + cd /srv/dev/hugo/wiki + rm -rf content static + ln -s /srv/docs/public content + ln -s /srv/docs/public/static static + ``` +2. **Preview Changes**: + ```bash + hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/" + ``` ## 🚀 CI/CD Pipeline -Deployment is fully automated through Gitea Actions. +Deployment is fully automated through Gitea Actions stored in the **Content repositories** (e.g., `docs-public/.gitea/workflows/deploy.yaml`). -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. +During a build, the Runner dynamically clones this Framework via HTTPS, injects the Markdown files from the triggering repository, applies the `editURL` overrides, builds the site, and deploys directly into the Nginx web server volume (`/srv/caddy/sites`). ---- - -## 💻 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/ +*(Note: The volume name `/srv/caddy` is a legacy name; the servers actually running are lightweight `nginx:alpine` containers defined in `gitea/docker-compose.yaml`)*. \ No newline at end of file