c743416ded
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>
57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
# 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).
|