From a1851165f47a0e0bae41028848abaf8f95181b06 Mon Sep 17 00:00:00 2001 From: wompmacho Date: Sun, 29 Mar 2026 01:50:09 +0000 Subject: [PATCH] update for readme to reflect changes for include --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1f624f0..9a81935 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,35 @@ +--- +title: "Project: Hugo Documentation Framework (Blowfish)" +description: "Architecture, local development, and deployment documentation for the central Hugo framework repository." +author: wompmacho +date: '2026-03-28T22:05:00-04:00' +lastmod: '2026-03-28' +tags: [hugo, framework, architecture, deployment, readme] +--- + # Project: Hugo Documentation Framework (Blowfish) -This repository manages the **Hugo build environment** (config, themes, and layouts) for both the Public and Private Wikis. +This repository (`hugo-framework`) manages the core **Hugo build environment** (engine, Blowfish theme, layouts, partials, and base configuration) for both the Public and Private Wikis. ## 🏗️ Architecture 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), 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`). +1. **Framework (`/srv/dev/hugo/wiki`)**: Contains the Hugo engine, themes, custom shortcodes (like `include`), and the **default configuration**. +2. **Public Content (`/srv/docs/public`)**: Contains the Markdown files and assets for the public-facing wiki. +3. **Private Content (`/srv/docs/private`)**: Contains the Markdown files and assets for the internal/private wiki. **Dynamic Configuration Merging:** The Framework defines the base styling in `config/_default/params.toml`. -However, the Content repositories can dynamically override: +However, the Content repositories can dynamically override settings during the build: * **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. +* **Theme Settings (Edit Links)**: Injected via Environment Variables (`HUGO_PARAMS_ARTICLE_EDITURL`) during the CI/CD pipeline to avoid hardcoding repository URLs in the base framework. ## 💻 Local Development ("Live Link") -To write documentation with real-time previews, you use symbolic links on your host machine: +To write documentation with real-time previews, use symbolic links on your host machine to connect a content repository to the framework: -1. **Establish Symlinks**: +1. **Establish Symlinks** (Example for Public Docs): ```bash cd /srv/dev/hugo/wiki rm -rf content static @@ -32,10 +41,37 @@ To write documentation with real-time previews, you use symbolic links on your h hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/" ``` -## 🚀 CI/CD Pipeline +## 🚀 CI/CD Pipeline & Deployment -Deployment is fully automated through Gitea Actions stored in the **Content repositories** (e.g., `docs-public/.gitea/workflows/deploy.yaml`). +Deployment is fully automated through Gitea Actions stored in the **Content repositories** (e.g., `.gitea/workflows/deploy.yaml`). **Manual builds to production should be avoided.** -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`). +**The Build Process:** +1. The Gitea Runner checks out the triggering content repository. +2. It clones this Framework repository dynamically. +3. It injects the Markdown files and static assets into the framework. +4. It builds the static HTML site using Hugo. +5. The generated files are copied directly into the persistent web server volumes: + * Public Wiki: `/srv/www/docs-public` + * Private Wiki: `/srv/www/docs-private` -*(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 +These directories are then served by their respective Dockerized Nginx containers. + +## 📂 File Inclusions (Absolute Paths) + +To allow for the inclusion of raw files outside of the standard Hugo `content/` directory (such as system configurations located in `/srv/configs`), this framework utilizes **Hugo Module Mounts** mapping into the virtual `assets/` directory. + +### How it Works + +Hugo's `readFile` and `fileExists` functions are blocked by strict OS security policies and cannot read paths outside the project root. To bypass this safely: +1. The external directory is mounted in `config/_default/hugo.toml`: + ```toml + [[module.mounts]] + source = "/srv/configs" + target = "assets/srv/configs" + ``` +2. The custom `include.html` shortcode (`{{< include "/srv/configs/..." >}}`) detects paths starting with `/srv/`, trims the leading slash, and uses `resources.Get` to fetch the raw file from the virtual `assets/` namespace, completely bypassing the Markdown parser and security blocks. + +**⚠️ Critical Note on CI/CD for External Files:** +If you map new external directories in `hugo.toml` (e.g., `/srv/newfolder`), the Docker container running the Gitea Action must also have OS-level access to those files. You must: +1. Allow the volume in the host's Gitea runner config (`/srv/gitea/runner/config.yaml` -> `valid_volumes`). +2. Mount the volume in the job options of the content repository's `.gitea/workflows/deploy.yaml` (e.g., `options: --user root -v /srv/www:/srv/www -v /srv:/srv:ro`).