Project: Hugo Documentation Framework (Blowfish)

This repository manages the Hugo build environment (config, themes, and layouts) 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).

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:

   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:

   hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/"
   

🚀 CI/CD Pipeline

Deployment is fully automated through Gitea Actions stored in the Content repositories (e.g., docs-public/.gitea/workflows/deploy.yaml).

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).

(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).