sjat c743416ded

Build docs site / build (push) Successful in 32s

Details

Build slides / build (push) Successful in 52s

Details

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

2.3 KiB

Raw Blame History

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.

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

Common targets:

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 for the full working norms and AI-collaboration guidance.

License

MIT — see LICENSE.