feat(docs): MkDocs Material site + auto-generated hardware overview
Bootstraps an MkDocs Material documentation site (rendered to
docs.makerfloss.eu by the Forgejo Actions runner). The first feature
is an auto-generated hardware overview built from per-host YAML
frontmatter blocks under docs/hardware/.
- mkdocs.yml, requirements.txt: MkDocs Material 9.5 + pyyaml
- Makefile: docs-index | docs-build | docs-serve | docs-check
- scripts/gen_overview.py: stdlib + pyyaml generator, deterministic and
offline. Reads scripts/overview_config.yml — category-driven so
services/vms can plug in later without touching the script.
- scripts/overview_config.yml: hardware schema and index layout
- docs/hardware/{makerfloss,fisi,tembo}.md: 3 sample entries
- docs/hardware/index.md: GENERATED, committed (CI fails on drift)
- docs/index.md: site landing page
- .forgejo/workflows/docs.yml: drift-check + mkdocs build --strict +
rsync site/ to /srv/docs-makerfloss/html on push to main
- .gitignore: site/, .venv, __pycache__
Schema:
- hostname, kind, status (required; kind/status are enums)
- model, location, cpu, cpu_cores, cpu_threads, ram_gb, storage_gb,
storage_type (enum), storage_notes, nic_gbps (all optional)
- Filename stem MUST equal hostname (enforced by generator)
- Extra optional fields are accepted silently and live on the per-page
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 21:10:58 +02:00
|
|
|
# MakerFLOSS Docs
|
|
|
|
|
|
|
|
|
|
Documentation for the [MakerFLOSS](https://forgejo.makerfloss.eu/sjat/MakerFLOSS)
|
|
|
|
|
initiative at [Orange Makerspace](https://orangemakers.dk) — a bi-weekly FLOSS
|
|
|
|
|
jam-session community focused on self-hosted, open-source infrastructure.
|
|
|
|
|
|
|
|
|
|
## Sections
|
|
|
|
|
|
|
|
|
|
- [Hardware](hardware/index.md) — every machine in the lab, auto-indexed from per-host
|
|
|
|
|
frontmatter blocks. Use this when planning where to deploy a new service.
|
2026-05-18 17:54:24 +02:00
|
|
|
- [Services](services/index.md) — the things we run on (or around) that
|
|
|
|
|
hardware: the docs site, slides, Forgejo, DNS, the slide-builder
|
|
|
|
|
toolchain, and so on.
|
2026-05-18 17:07:26 +02:00
|
|
|
- [House rules](house-rules.md) — working norms, governance, and
|
feat(docs): MkDocs Material site + auto-generated hardware overview
Bootstraps an MkDocs Material documentation site (rendered to
docs.makerfloss.eu by the Forgejo Actions runner). The first feature
is an auto-generated hardware overview built from per-host YAML
frontmatter blocks under docs/hardware/.
- mkdocs.yml, requirements.txt: MkDocs Material 9.5 + pyyaml
- Makefile: docs-index | docs-build | docs-serve | docs-check
- scripts/gen_overview.py: stdlib + pyyaml generator, deterministic and
offline. Reads scripts/overview_config.yml — category-driven so
services/vms can plug in later without touching the script.
- scripts/overview_config.yml: hardware schema and index layout
- docs/hardware/{makerfloss,fisi,tembo}.md: 3 sample entries
- docs/hardware/index.md: GENERATED, committed (CI fails on drift)
- docs/index.md: site landing page
- .forgejo/workflows/docs.yml: drift-check + mkdocs build --strict +
rsync site/ to /srv/docs-makerfloss/html on push to main
- .gitignore: site/, .venv, __pycache__
Schema:
- hostname, kind, status (required; kind/status are enums)
- model, location, cpu, cpu_cores, cpu_threads, ram_gb, storage_gb,
storage_type (enum), storage_notes, nic_gbps (all optional)
- Filename stem MUST equal hostname (enforced by generator)
- Extra optional fields are accepted silently and live on the per-page
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 21:10:58 +02:00
|
|
|
what we do (and don't) do.
|
|
|
|
|
|
|
|
|
|
## Working norms (summary)
|
|
|
|
|
|
|
|
|
|
- **Language:** English for code and docs. Danish allowed in meeting notes and
|
|
|
|
|
community communications.
|
|
|
|
|
- **Environments:** containerised and reproducible.
|
|
|
|
|
- **Hardware:** all setups documented (this site) and physically labelled.
|
|
|
|
|
- **Decisions:** lightweight markdown decision logs under
|
2026-05-18 16:53:27 +02:00
|
|
|
[`notes/dev/`](https://forgejo.makerfloss.eu/sjat/MakerFLOSS/src/branch/main/notes/dev).
|
feat(docs): MkDocs Material site + auto-generated hardware overview
Bootstraps an MkDocs Material documentation site (rendered to
docs.makerfloss.eu by the Forgejo Actions runner). The first feature
is an auto-generated hardware overview built from per-host YAML
frontmatter blocks under docs/hardware/.
- mkdocs.yml, requirements.txt: MkDocs Material 9.5 + pyyaml
- Makefile: docs-index | docs-build | docs-serve | docs-check
- scripts/gen_overview.py: stdlib + pyyaml generator, deterministic and
offline. Reads scripts/overview_config.yml — category-driven so
services/vms can plug in later without touching the script.
- scripts/overview_config.yml: hardware schema and index layout
- docs/hardware/{makerfloss,fisi,tembo}.md: 3 sample entries
- docs/hardware/index.md: GENERATED, committed (CI fails on drift)
- docs/index.md: site landing page
- .forgejo/workflows/docs.yml: drift-check + mkdocs build --strict +
rsync site/ to /srv/docs-makerfloss/html on push to main
- .gitignore: site/, .venv, __pycache__
Schema:
- hostname, kind, status (required; kind/status are enums)
- model, location, cpu, cpu_cores, cpu_threads, ram_gb, storage_gb,
storage_type (enum), storage_notes, nic_gbps (all optional)
- Filename stem MUST equal hostname (enforced by generator)
- Extra optional fields are accepted silently and live on the per-page
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 21:10:58 +02:00
|
|
|
- **License:** FLOSS by default; MIT for what we build.
|