MakerFLOSS/docs/guides/editing-hardware-docs.md

title
Editing the hardware docs

Editing the hardware docs

The hardware inventory is one Markdown file per device under docs/hardware/. The YAML frontmatter at the top of each file is the single source of truth. Everything you see rendered — the Hardware Overview table, the per-device Specs box, the rack elevation SVG, and the network graph — is generated from that frontmatter.

!!! warning "The golden rule" After editing any file in docs/hardware/, run make docs-index and commit the regenerated files. CI rebuilds the indices and fails the build if they differ from what you committed. This is the single most common reason a push goes red.

Quick start: add a device

1. Pick a hostname following the scheme <kind-abbrev><NN> — a 2-digit number, unique per kind (srv, sw, pp, pdu, ups, shf, …). Example: srv06.
2. Create docs/hardware/<hostname>.md. The filename stem must equal the hostname field — srv06.md must contain hostname: srv06.
3. Fill in the frontmatter (see the reference below). Write any free-text under ## Notes.
4. Run make docs-index and commit both your new file and the regenerated index / rack files.

---
hostname: srv06
kind: server
status: staging
location: The pile
cpu: Intel Core i5-3570K @ 3.40GHz
cpu_cores: 4
cpu_threads: 4
ram_gb: 8
storage_gb: 500
storage_type: hdd
nic_gbps: 1
rack: rack01
rack_u: 7
u_height: 2
rack_face: front
power:
  - { pdu: pdu01, outlet: 5 }
links:
  - { local: eth0, peer: sw01, peer_port: 6, speed_gbps: 1 }
---

## Notes

Donated tower; PSU replaced 2026-06.

Frontmatter reference

Required on every device

Field	Notes
hostname	Must equal the filename stem.
kind	One of the enum below.
status	One of the enum below.

kind — server, laptop, sbc, switch, ap, desktop, pdu, patch-panel, shelf, blank, ups, kvm.

status — in-use, staging, spare, broken, donated.

Specs (optional, shown in the table and Specs box)

Field	Example	Notes
location	The pile	Free text.
cpu	Intel Core i5-3570K @ 3.40GHz	Model string.
cpu_cores / cpu_threads	4 / 8	Integers; threads shown only if they differ from cores.
ram_gb	8	Integer (rendered as 8 GB).
storage_gb + storage_type	500 + hdd	storage_type ∈ nvme, ssd, hdd, mixed.
storage	[{gb: 500, type: ssd}, {gb: 2000, type: hdd}]	List form for multiple drives (alternative to the two fields above).
nic_gbps	1 or [1, 10]	Number or list (rendered as GbE).

Placement in a rack

Only files that declare a rack: appear in a rack elevation. The rack is 48U.

=== "Front / rear (U-mounted)"

```yaml
rack: rack01
rack_face: front     # front | rear | both
rack_u: 7            # starting U (1–48)
u_height: 2          # height in U (≥1)
```

`both` occupies the same U range on **front and rear**. Two U-mounted
devices may not overlap on the same face.

=== "0U side rail (e.g. vertical PDU)"

```yaml
rack: rack01
rack_face: left      # left | right
# no rack_u / u_height
```

Side-rail (`left`/`right`) items are 0U and **must omit** `rack_u` and
`u_height`.

=== "Shelf-mounted"

```yaml
rack: rack01
mounted_on: shf01    # an existing kind:shelf in the same rack
shelf_face: front    # front | rear
shelf_slot: 2        # integer ≥1
# no rack_u / u_height / rack_face
```

The shelf itself must be placed (have `rack_u` + `u_height`). Two devices
can't share the same `(shelf, face, slot)`.

Power feeds

A device draws power by listing feeds. Each feed must point at a real kind:pdu file, and the outlet must be within that PDU's outlets count.

power:
  - { pdu: pdu01, outlet: 5 }

A pdu device must declare a positive integer outlets: (e.g. outlets: 8).

Network links

Links feed the network graph. peer is the hostname of a switch / patch-panel / peer device.

links:
  - { local: eth0, peer: sw01, peer_port: 6, speed_gbps: 1 }

The make process

Command	What it does
make docs-index	Regenerate the hardware/services indices and rack elevations from frontmatter. Run this after every edit.
make docs-check	Regenerate, then fail if the result differs from the committed copies — exactly what CI runs.
make docs-build	Build the static site with mkdocs build --strict.
make docs-serve	Live-reload local preview at http://127.0.0.1:8000.
make test	Run the Python unit tests (pytest).

A typical edit loop:

$EDITOR docs/hardware/srv06.md
make docs-index          # regenerate
make docs-check          # confirm no drift (optional sanity check)
git add docs/hardware/srv06.md docs/hardware/index.md docs/infrastructure/racks/
git commit -m "hardware: add srv06"
git push                 # CI builds and publishes to docs.makerfloss.eu

On push to main, CI regenerates the indices, runs the drift check, builds the site strictly, and publishes it. If you forgot make docs-index, the drift check fails and nothing is published.

Dos and don'ts

!!! success "Do" - Do run make docs-index and commit the regenerated files with your change. - Do keep the filename equal to the hostname. - Do use the <kind-abbrev><NN> naming scheme, 2 digits, unique per kind. - Do mark unknown values as provisional placeholders and ask before inventing rack/power/network numbers. - Do preview locally with make docs-serve before pushing.

!!! danger "Don't" - Don't hand-edit generated files — docs/hardware/index.md, docs/services/index.md, docs/infrastructure/racks/*.md, and the *-elevation.svg files all carry a "do not edit by hand" banner and will be overwritten. - Don't put non-device Markdown into docs/hardware/ — the generators scan that folder and expect host frontmatter. Guides like this one live in docs/guides/. - Don't give a 0U side-rail item (left/right) a rack_u/u_height, and don't give a U-mounted item a side-rail face — the generator rejects both. - Don't point power at a non-PDU, or use an outlet number beyond the PDU's outlets count. - Don't rename a file without renaming the hostname to match.