41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# 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**:
|
|
```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 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`)*. |