moonweb-site/SPEC.md

moonweb.org — Specification

Status: Concept finalized. This document defines what gets built. See PLAN.md for how and in what order.

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.

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

outside the monorepo, untouched:
├── stefankoelle.de          CV, career, personal (extern gehostet)
├── www.moonweb.org          finished, no overlap (2001-style internet time capsule)
├── 28k8.moonweb.org         90s BBS/scene archive, separate approach, may migrate later (undecided)
└── home.moonweb.org         Authelia-protected homelab dashboard/control plane (not part of this site set)

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. Cloudflare Free-Tier limits to 5 Pages projects per repository, which is why cv (stefankoelle.de) stays external.

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 home.moonweb.org 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

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: current home.moonweb.org — banner header, grouped card sections, clean 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).

Note: cv (stefankoelle.de) is external and uses its own independent design — it does not follow this 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)

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. cv (stefankoelle.de) follows its own existing URL patterns and is not part of this convention.

5. Content depth rules (per domain)

Domain	Detail pages?	Rule
smarthome	Yes, when there's enough content	Index shows how the smart home is structured; a topic gets a detail page immediately if enough data exists — otherwise it's mentioned in the overview only, no placeholder required
code	Never	Overview cards + link to GitHub only. No duplicating README content.
infra	Rarely	Deliberately shallow — most of the raw material is sensitive (see §6)
retro	Yes, but minimal	Topic is still immature; create only a rudimentary overview, don't over-invest time

General rule across all domains: if content is too thin for a good detail page, skip the detail page — don't create a placeholder.

Note: cv (stefankoelle.de) is external and not subject to these rules.

6. Infra content redaction rule

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. cv (stefankoelle.de) is maintained separately and not subject to this rule.

7. Language

All five sites (hub, infra, smarthome, code, retro) 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. cv (stefankoelle.de) remains in its existing language.

8. GitHub automation (code.moonweb.org)

Each GitHub project repo gets a .moonweb.yml in its root:

title: "MVG Departures"
category: code          # code | smarthome | infra
subcategory: "Web Apps" # drives grouping on code.moonweb.org
status: active
stack: [Python, FastAPI]
hosted_on: "Docker Host Debian (PVE)"
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. cv (stefankoelle.de) is not included in this automation.

9. Content maintenance

• infra, smarthome, retro: fully manual, edited in vim, committed via git push. No automation.
• code: the only automated piece is the GitHub aggregator described in §8.
• No "last updated" timestamps are shown anywhere — the goal is that content is simply kept current, not that staleness is displayed.
• No analytics/tracking of any kind on any of the five sites.
• Images/assets live versioned directly in the monorepo (no external asset host).
• cv (stefankoelle.de): maintained separately, linked from hub/site-switcher.

10. Repository structure

moonweb-site/
├── hub/
├── infra/
├── smarthome/
├── code/
│   └── _data/repos.json     # populated by the GitHub aggregator
├── retro/
├── shared/
│   ├── _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
├── 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 each to its Cloudflare Pages project

Note: cv/ (stefankoelle.de) is hosted externally and linked from hub/site-switcher — it is not part of this monorepo (Cloudflare Free-Tier limits to 5 Pages projects per repository).

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.
• 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. One shared GitHub Actions workflow builds all five sites and deploys each output folder to its respective Pages project.
• Cloudflare Free-Tier limit: Max 5 Pages projects per repository — cv (stefankoelle.de) stays external to avoid hitting this limit.
• 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.

12. Explicitly out of scope for this build

• Migrating /ledmatrix/ (and any other existing stefankoelle.de sub-pages) into smarthome — stays linked externally for now, migrates in a later phase.
• 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.
• 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.
• Porting stefankoelle.de into the monorepo — stays external (Cloudflare Free-Tier limits to 5 Pages projects per repository).