MakerFLOSS/README.md

# MakerFLOSS

Documentation and working notes for **MakerFLOSS**, an Orange Makerspace initiative — a bi-weekly FLOSS jam-session community focused on self-hosted, open-source infrastructure.

- Live docs: <https://docs.makerfloss.eu>
- Slides: <https://slides.makerfloss.eu>
- Source: <https://forgejo.makerfloss.eu/sjat/MakerFLOSS>

## Repository layout

```
docs/             # built into the public site (docs.makerfloss.eu)
  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
  services/       # auto-indexed per-service frontmatter (docs, forgejo, …)
  infrastructure/ # labdesign, VPS/DNS, etc.
  presentations/  # Marp decks (also published to slides.makerfloss.eu)
notes/            # repo-only working material — not part of the site
  meetings/       # meeting notes (Danish allowed)
  todo/           # task lists, working norms, wishlist, services
  dev/            # internal plans/ and specs/
  communications/ # community comms artefacts
sandbox/          # scratch / pipeline fixtures
scripts/          # build helpers (hardware index, mkdocs hook)
```

## Building locally

Requires Python 3.10+ and, for slide builds, either `marp` on `$PATH` or Docker.

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

Common targets:

```bash
make docs-serve   # live-reload preview at http://127.0.0.1:8000
make docs-build   # strict build into ./site
make docs-index   # regenerate docs/hardware/index.md from per-host frontmatter
make docs-check   # CI drift-check for the hardware index
make slides       # build Marp decks (docs/presentations/*.md) into ./slides
```

CI runs on the self-hosted Forgejo Actions runner (`.forgejo/workflows/docs.yml`) and rsyncs the built site to the VPS.

## Conventions

- **Filenames**: ASCII lowercase, kebab-case (`like-this.md`). Dated docs use `YYYY-MM-DD-label.md`. Hardware host pages are the exception — their filename stem must equal the `hostname` field, enforced by `scripts/gen_overview.py`.
- **Languages**: English for code and docs; Danish allowed in meeting notes and community communications.
- **Git**: Trunk-based, feature branches, simple commit messages, no secrets in commits.

See [`CLAUDE.md`](CLAUDE.md) for the full working norms and AI-collaboration guidance.

## License

MIT — see [`LICENSE`](LICENSE).
Initial commit 2026-03-17 10:39:20 +01:00			`# MakerFLOSS`

docs: add proper README at repo root and per-tree READMEs - Rewrite the 84-byte Danish placeholder README.md into a proper English entry point: what this repo is, live URLs, layout, build instructions (make targets), and conventions, with pointers to CLAUDE.md for the long form. - Add short READMEs to notes/, sandbox/, and scripts/ so each tree documents its own purpose at the boundary where someone is likely to land on it via the Forgejo web UI or a clone. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> 2026-05-18 17:13:50 +02:00			`Documentation and working notes for MakerFLOSS, an Orange Makerspace initiative — a bi-weekly FLOSS jam-session community focused on self-hosted, open-source infrastructure.`

			`- Live docs: <https://docs.makerfloss.eu>`
			`- Slides: <https://slides.makerfloss.eu>`
			`- Source: <https://forgejo.makerfloss.eu/sjat/MakerFLOSS>`

			`## Repository layout`

			```
			`docs/ # built into the public site (docs.makerfloss.eu)`
docs: record hardware naming scheme, refresh stale mf0x hints 2026-06-24 16:26:11 +02:00			`hardware/ # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)`
feat(docs): add services category alongside hardware Mirror the auto-indexed per-host pattern for a new docs/services/ category, seeded with the six things currently deployed on or around makerfloss.eu: docs, slides, forgejo, gandi-dns, marp, mermaid. Generator/hook generalisation: - scripts/gen_overview.py: replace the hardcoded `hostname` check with a configurable `key_field` (default: hostname). Add a generic `key-link` column kind (replaces the old `hostname-link`) and a `url-link` kind that renders the value as a clickable link. - scripts/overview_config.yml: declare hardware's key_field, then add a `services` block (key_field=name, its own kind/status enums, grouped by kind for the index table). - scripts/mkdocs_hooks.py: route by `page.file.src_uri` so each hardware/* page gets a "Specs" table and each services/* page gets a "Service" table; both share the helpers in gen_overview. Wiring: - Makefile: docs-index and docs-check now regenerate and drift-check both indices. - .forgejo/workflows/docs.yml: same on the CI runner. - mkdocs.yml: add Services to nav. - README.md, CLAUDE.md: list services/ in the repo-layout block. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> 2026-05-18 17:48:15 +02:00			`services/ # auto-indexed per-service frontmatter (docs, forgejo, …)`
docs: add proper README at repo root and per-tree READMEs - Rewrite the 84-byte Danish placeholder README.md into a proper English entry point: what this repo is, live URLs, layout, build instructions (make targets), and conventions, with pointers to CLAUDE.md for the long form. - Add short READMEs to notes/, sandbox/, and scripts/ so each tree documents its own purpose at the boundary where someone is likely to land on it via the Forgejo web UI or a clone. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> 2026-05-18 17:13:50 +02:00			`infrastructure/ # labdesign, VPS/DNS, etc.`
			`presentations/ # Marp decks (also published to slides.makerfloss.eu)`
			`notes/ # repo-only working material — not part of the site`
			`meetings/ # meeting notes (Danish allowed)`
			`todo/ # task lists, working norms, wishlist, services`
			`dev/ # internal plans/ and specs/`
			`communications/ # community comms artefacts`
			`sandbox/ # scratch / pipeline fixtures`
			`scripts/ # build helpers (hardware index, mkdocs hook)`
			```

			`## Building locally`

			Requires Python 3.10+ and, for slide builds, either `marp` on `$PATH` or Docker.

			```bash
			`python3 -m venv .venv && source .venv/bin/activate`
			`pip install -r requirements.txt`
			```

			`Common targets:`

			```bash
			`make docs-serve # live-reload preview at http://127.0.0.1:8000`
			`make docs-build # strict build into ./site`
			`make docs-index # regenerate docs/hardware/index.md from per-host frontmatter`
			`make docs-check # CI drift-check for the hardware index`
			`make slides # build Marp decks (docs/presentations/*.md) into ./slides`
			```

			CI runs on the self-hosted Forgejo Actions runner (`.forgejo/workflows/docs.yml`) and rsyncs the built site to the VPS.

			`## Conventions`

			- Filenames: ASCII lowercase, kebab-case (`like-this.md`). Dated docs use `YYYY-MM-DD-label.md`. Hardware host pages are the exception — their filename stem must equal the `hostname` field, enforced by `scripts/gen_overview.py`.
			`- Languages: English for code and docs; Danish allowed in meeting notes and community communications.`
			`- Git: Trunk-based, feature branches, simple commit messages, no secrets in commits.`

			See [`CLAUDE.md`](CLAUDE.md) for the full working norms and AI-collaboration guidance.

			`## License`

			MIT — see [`LICENSE`](LICENSE).