# 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 (mf00..mf03, 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).