stefankoelle/moonweb-site
1
0
Fork 0
mirror of https://github.com/skoelle/moonweb-site.git synced 2026-09-17 17:00:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update all documentation for consolidated www.moonweb.org structure

Browse Source 
- AGENTS.md: new file structure, single config, correct commands
- README.md: updated architecture, project structure, CI/CD docs
- SPEC.md: updated sitemap, design system, repository structure, tech stack
- PLAN.md: completed migration phases, remaining items
- TODO.md: current status, completed tasks, remaining items
This commit is contained in:
stefankoelle
2026-09-11 14:07:05 +02:00
parent 01097ff89a
commit 9ffbadb3db
5 changed files with 287 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SPEC.md
+86 -67
View File
@@ -1,63 +1,69 @@
# moonweb.org — Specification
Status: Concept finalized. This document defines *what* gets built. See `PLAN.md` for *how and in what order*.
Status: Migration complete. All sites live under `www.moonweb.org` as subdirectories, deployed via IONOS SFTP.
## 1. Purpose
A personal homelab hub consisting of a central index (`hub`) and several themed static sites, replacing the current unstructured presentation of infrastructure, smart home projects, and GitHub repos. cv (stefankoelle.de) remains external, linked from the hub and site-switcher.
A personal homelab hub consisting of a central index (`hub` at root) and several themed static sites, all served under `www.moonweb.org` as subdirectories. The old timecapsule content (2001 design) is preserved under `/timecapsule/`. cv (stefankoelle.de) remains external, linked from the hub and site-switcher.
## 2. Sitemap
```
moonweb-site (monorepo)
├── hub/ → hub.moonweb.org Central index & gateway
├── infra/ → infra.moonweb.org System architecture / stack overview
├── smarthome/ → smarthome.moonweb.org What the homelab actually runs, and why
├── code/ → code.moonweb.org Curated GitHub catalog
├── retro/ → retro.moonweb.org Physical retro hardware collection
└── stefankoelle/→ stefankoelle.de CV, career, personal site (SFTP deploy)
├── hub/ → www.moonweb.org/ Central index & gateway
├── infra/ → www.moonweb.org/infra/ System architecture / stack overview
├── smarthome/ → www.moonweb.org/smarthome/ What the homelab actually runs, and why
├── code/ → www.moonweb.org/code/ Curated GitHub catalog
├── retro/ → www.moonweb.org/retro/ Physical retro hardware collection
├── timecapsule/ → www.moonweb.org/timecapsule/ 2001-era internet time capsule
└── stefankoelle/→ stefankoelle.de CV, career, personal site (SFTP deploy)
outside the monorepo, untouched:
├── www.moonweb.org finished, no overlap (2001-style internet time capsule)
├── 28k8.moonweb.org 90s BBS/scene archive, separate approach, may migrate later (undecided)
├── 28k8.moonweb.org 90s BBS/scene archive
├── buildbroken.moonweb.org .NET Open Space blog archive
```
Apex domain `moonweb.org` currently redirects to `www.moonweb.org`. This stays as-is for now; a later redirect to `hub.moonweb.org` is possible but out of scope for this build.
Old subdomain redirects (via Cloudflare):
- `hub.moonweb.org/*` → `www.moonweb.org/*`
- `infra.moonweb.org/*` → `www.moonweb.org/infra/*`
- `smarthome.moonweb.org/*` → `www.moonweb.org/smarthome/*`
- `code.moonweb.org/*` → `www.moonweb.org/code/*`
- `retro.moonweb.org/*` → `www.moonweb.org/retro/*`
## 3. Domain purposes
| Domain | Purpose | Tone |
|---|---|---|
| hub | Gateway, links to everything, one-line description per destination | Minimal |
| infra | Shallow, structured overview of the stack: Proxmox (PVE + pve2), Synology DS918+, VLANs, Fritz!Box mesh, SSO, plus how I work (OpenCode/OpenClaw dev environment) | Reference, high-level only |
| smarthome | Why the homelab exists — what's actually running on the homelab as smart home: sensors, automation, calendar/contacts sync, dashboards, media | Project storytelling |
| code | Curated, sorted GitHub catalog — overview only, always linking out to GitHub | Portfolio |
| retro | Physical retro hardware collection (not software/demos — that's 28k8's domain) | Simple, factual |
| Domain | URL | Purpose | Tone |
|---|---|---|---|
| hub | `/` | Gateway, links to everything, one-line description per destination | Minimal |
| infra | `/infra/` | Shallow, structured overview of the stack: Proxmox, Synology, VLANs, Docker hosting, dev environment | Reference, high-level only |
| smarthome | `/smarthome/` | Why the homelab exists — sensors, automation, calendar/contacts sync, dashboards, media | Project storytelling |
| code | `/code/` | Curated, sorted GitHub catalog — overview only, always linking out to GitHub | Portfolio |
| retro | `/retro/` | Physical retro hardware collection (not software/demos — that's 28k8's domain) | Simple, factual |
| timecapsule | `/timecapsule/` | Original www.moonweb.org content from 2001, preserved as-is | Retro 2001 design |
## 4. Design system
### 4.1 Header-consistent, content-flexible principle
- **Header is identical** across infra/smarthome/code/retro: site-switcher (hub · infra · smarthome · code · retro), domain accent color, consistent branding.
- **Overview (index) pages** use a shared card-grid layout (reference: clean card-grid layout with banner header, grouped card sections, sans-serif, generous whitespace, light theme only, no heavy JS).
- **Detail/sub-pages** keep the same header but may use a freer layout below it (reference: `/ledmatrix/` on stefankoelle.de today — pin tables, API docs, photos in free layout instead of a rigid card grid).
- **Header is identical** across all sites: site-switcher (home · infra · smarthome · code · retro · cv), section title (`moonweb.org` or `moonweb.org/smarthome`), domain accent color.
- **Overview (index) pages** use a shared card-grid layout (clean card-grid with banner header, grouped card sections, sans-serif, generous whitespace, light theme only, no heavy JS).
- **Detail/sub-pages** keep the same header but may use a freer layout below it.
Note: stefankoelle.de is now part of the monorepo but uses its own independent design — it does not follow this header-consistent principle.
Note: stefankoelle.de uses its own independent design — it does not follow this header-consistent principle.
### 4.2 Accent colors per domain
| Domain | Accent |
|---|---|
| hub | Neutral blue |
| infra | Grey-blue |
| smarthome | Teal |
| code | Violet |
| retro | Own accent, still clean card-grid (no 90s styling — that belongs to 28k8) |
| Domain | Accent | Implementation |
|---|---|---|
| hub | Neutral blue (#3b6ea5) | Inlined `<style>` in base.njk |
| infra | Red (#99333A) | Inlined `<style>` in base.njk |
| smarthome | Teal (#1f8a8a) | Inlined `<style>` in base.njk |
| code | Violet (#3E5098) | Inlined `<style>` in base.njk |
| retro | Brown (#8a6d3b) | Inlined `<style>` in base.njk |
### 4.3 URL convention
`domain/slug/` — lowercase, hyphenated, trailing slash, matching the existing stefankoelle.de pattern (e.g. `/ledmatrix/`) so future detail pages stay consistent even if content later migrates between sites.
`/section/slug/` — lowercase, hyphenated, trailing slash. All sites share a single Eleventy build with computed `pathPrefix` per section.
## 5. Content depth rules (per domain)
@@ -77,20 +83,20 @@ Because infra must stay shallow and public-safe:
- **Allowed:** architecture level — Proxmox + Synology + Docker host, VLAN concept without concrete internal IP plans, which service types run, which tools are used.
- **Not allowed:** concrete IP addresses, WireGuard keys/preshared keys, passwords, internal hostnames that allow inference, backup targets with credentials.
This rule applies to any domain but is most relevant for infra, since the source documents (e.g. Heimnetzwerk-Final-v3.2, GL_Flint2_Final_v2) currently contain real IPs and keys that must be actively stripped during migration.
This rule applies to any domain but is most relevant for infra, since the source documents currently contain real IPs and keys that must be actively stripped during migration.
## 7. Language
All sites in the monorepo are written **entirely in English**. Existing German source documents are translated once during migration via a single AI-assisted pass — not a recurring process. New `.moonweb.yml` metadata and generated content are authored in English from the start.
## 8. GitHub automation (code.moonweb.org)
## 8. GitHub automation (www.moonweb.org/code/)
Each GitHub project repo gets a `.moonweb.yml` in its root:
```yaml
title: "MVG Departures"
category: code # code | smarthome | infra
subcategory: "Web Apps" # drives grouping on code.moonweb.org
subcategory: "Web Apps" # drives grouping on www.moonweb.org/code/
status: active
stack: [Python, FastAPI]
hosted_on: "Docker Host Debian (PVE)"
@@ -98,7 +104,7 @@ summary: "Compact MVG/S-Bahn departure monitor with configurable stations."
repo_url: "https://github.com/skoelle/mvg-departures"
```
A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API, an AI pass turns the raw YAML into readable card copy, and the result is committed into `code/_data/repos.json` inside the monorepo. This runs manually, on demand — no scheduled automation for now.
A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API, and the result is committed into `_data/repos.json` inside the monorepo. This runs manually, on demand — no scheduled automation for now.
## 9. Content maintenance
@@ -112,47 +118,60 @@ A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API
```
moonweb-site/
├── hub/
├── infra/
├── smarthome/
├── code/
│ └── _data/repos.json # populated by the GitHub aggregator
├── retro/
├── stefankoelle/ # CV, career, personal site
├── hub/ # Index + Redirects (.htm) + impressum.njk
├── infra/ # Index.njk + 8 Subseiten
├── smarthome/ # Index.njk + 9 Subseiten
├── code/ # Index.njk
├── retro/ # Index.njk + 13 Subseiten
├── timecapsule/ # Eleventy 2.x (eigene Config)
│ ├── eleventy.config.js
│ ├── index.njk # Onepager (CV, Projects, Languages)
│ ├── cv-print.njk # CV-only for PDF generation
│ ├── ledmatrix/ # LED Matrix WebServer documentation
│ └── assets/ # CSS, JS, images, favicons
├── shared/
│ ├── package.json
│ └── src/
├── stefankoelle/ # Eleventy-Config + Onepager
│ ├── eleventy.config.js
│ ├── index.njk
│ ├── cv-print.njk
│ ├── ledmatrix/
│ └── assets/
├── shared/ # Shared components
│ ├── _includes/
│ │ ├── base.njk # shared header + footer layout
│ │ └── card-grid.njk # card-grid template
│ ├── base.css # shared CSS variables and layout
│ └── theme-*.css # one accent color file per domain
│ │ ├── base.njk # base layout (header, site-switcher, footer)
│ │ ├── card-grid.njk # card-grid template
│ │ └── sitemap.njk # central sitemap template
│ ├── base.css # shared CSS
│ └── favicon/ # favicon SVGs per section
├── _data/
│ └── repos.json # populated by the GitHub aggregator
├── scripts/
│ └── github-aggregator/ # reads .moonweb.yml from all repos
├── DESIGN.md # initial concept and design decisions
├── SPEC.md # what gets built (this document)
├── PLAN.md # how and in what order
├── TODO.md # open items and workflow
└── .github/workflows/
├── build-deploy.yml # builds all sites, deploys to Cloudflare Pages
└── deploy-stefankoelle.yml # builds stefankoelle, deploys via IONOS SFTP
│ ├── github-aggregator/ # reads .moonweb.yml from all repos
│ └── cloudflare/ # redirect setup for old subdomains
├── .github/workflows/
│ ├── build-deploy-moonweb.yml # builds all moonweb sites, deploys to IONOS SFTP
│ └── deploy-stefankoelle.yml # builds stefankoelle, deploys via IONOS SFTP
├── eleventy.config.js # single Eleventy config for all moonweb sites
├── .eleventyignore # excludes stefankoelle/, timecapsule/
├── DESIGN.md
├── SPEC.md
├── PLAN.md
├── TODO.md
└── package.json
```
## 11. Technical stack
- **Static site generator:** Eleventy (11ty) — markdown/YAML-first, minimal JS, `_data` folders map directly onto the `.moonweb.yml` aggregator output, low maintenance for five sites at this scale.
- **Static site generator:** Eleventy (11ty) v3.1.6 — single config at root, computed `pathPrefix` per section, per-section collections.
- **Static site generator (timecapsule):** Eleventy v2.0.1 — separate config, preserves original 2001 design.
- **Templates:** Nunjucks (.njk) — shared `base.njk` layout, `card-grid.njk` for index pages, `sitemap.njk` for central sitemap.
- **Styling:** Custom CSS (`base.css`) with accent colors inlined as `<style>` in `base.njk`. No per-site theme CSS files.
- **Build:** entirely in GitHub Actions.
- **Deploy:** Cloudflare Pages — five separate Pages projects (one per public domain: hub, infra, smarthome, code, retro), since Cloudflare Pages binds one custom-domain set per project. stefankoelle.de deploys via IONOS SFTP. Two GitHub Actions workflows handle deployment.
- **Runtime:** fully static, no server-side code, no containers for the website itself (distinct from the actual homelab services running on the Docker host).
- **DNS:** already on Cloudflare — no additional setup step needed for Pages custom domains.
- **Local preview:** Eleventy's built-in dev server with live reload, run per-site (`npm run dev:<site>`) before any commit.
- **Deploy:** IONOS SFTP — all sites deployed to `/websites/moonweb/`, stefankoelle.de to `/websites/stefankoelle/`.
- **DNS:** Cloudflare — DNS management + redirects from old subdomains (hub.moonweb.org, etc.).
- **Runtime:** fully static, no server-side code, no containers for the website itself.
- **Local preview:** Eleventy's built-in dev server with live reload (`npm run dev` for all moonweb sites, `npm run dev:stefankoelle`, `npm run dev:timecapsule`).
## 12. Explicitly out of scope for this build
## 12. Explicitly out of scope
- Migrating 28k8.moonweb.org into the monorepo — undecided, revisit later, likely never.
- Any Perplexity-backchannel mechanism (website content reusable inside this project) — deferred, no time invested now.
- Any Perplexity-backchannel mechanism — deferred.
- Analytics of any kind.
- Automated content generation/translation pipelines beyond the one-time GitHub aggregator for code and the one-time translation pass during migration.
- Automated content generation/translation pipelines beyond the one-time GitHub aggregator for code.