Netgrimoire/Documentation_Standards.md

title	description	published	date	tags	editor	dateCreated
Netgrimoire Documentation	How to create and use Netgrimoire Docs	true	2026-02-03T02:54:56.444Z		markdown	2026-02-03T02:54:56.444Z

Homelab Documentation Structure & Diagram Standards

This document describes the official documentation structure for the homelab Wiki.js instance, including:

• Folder and page layout
• Naming conventions
• How Git fits into the workflow
• How to use draw.io (diagrams.net) for diagrams
• How to ensure documentation is accessible when the lab is down

This page is intended to be a reference and enforcement guide.

---

Core Principles

1. Wiki.js is the editor, Git is the source of truth
2. All documentation must be readable without Wiki.js
3. Diagrams must be viewable without draw.io
4. Folder structure must be predictable and consistent
5. Emergency documentation must not depend on the lab being up

---

Repository Overview

All documentation lives in a single Git repository.

Wiki.js writes Markdown files into this repository automatically.
The repository can be cloned to a laptop or other device for offline access.

Example:

git clone ssh://git@forgejo.example.com/homelab/docs.git

---

Top-Level Folder Structure

homelab-docs/
├── README.md
├── emergency/
├── infrastructure/
├── storage/
├── services/
├── runbooks/
├── diagrams/
└── assets/

Folder Purpose

Folder	Purpose
README.md	Entry point when the lab is down
emergency/	Recovery procedures and break-glass docs
infrastructure/	Core systems (identity, backups, networking)
storage/	Storage platforms and layouts
services/	Application-specific documentation
runbooks/	Step-by-step operational procedures
diagrams/	All draw.io diagrams and exports
assets/	Images or files used by documentation

---

Storage Documentation Structure

storage/
└── core/
    ├── zfs.md
    ├── local-drives.md
    ├── nas.md
    └── btrfs.md

Guidelines:

• Each storage technology gets its own page
• Pages describe architecture, layout, and operational notes
• Backup and snapshot policies belong elsewhere

---

Infrastructure Documentation Structure

infrastructure/
└── backups/
    ├── zfs-snapshots.md
    └── application-backups.md

Guidelines:

• Infrastructure describes cross-cutting systems
• Anything used by multiple hosts or services belongs here
• Backup strategies are infrastructure, not storage

---

Services Documentation Structure

services/
└── mailcow.md

Guidelines:

• One page per service
• Page should include:
  • Purpose
  • Architecture
  • Volumes
  • Backup considerations
  • Recovery notes

---

Emergency Documentation

emergency/
├── bring-up-order.md
├── swarm-recovery.md
├── zfs-import.md
├── network-restore.md
└── identity-break-glass.md

Rules:

Emergency docs must be:

• Text-first
• Copy/paste friendly
• Free of dependencies

These pages should be readable directly from Git.

---

Naming Conventions (Mandatory)

Folders:

• Lowercase
• No spaces
• Example: infrastructure/backups

Page filenames:

• Lowercase
• Hyphen-separated
• Example: zfs-snapshots.md

Page titles:

• Human readable
• Proper case
• Example: # ZFS Snapshots

---

draw.io (diagrams.net) Usage

draw.io is used only to create diagrams, never as the sole storage location.

Diagram Storage Layout

diagrams/
├── network/
│   ├── core.drawio
│   ├── core.png
│   └── core.svg
├── docker/
│   ├── swarm-architecture.drawio
│   └── swarm-architecture.png
└── storage/
    ├── zfs-layout.drawio
    └── zfs-layout.png

File Types

File	Purpose
.drawio	Editable source
.png	Offline viewing
.svg	Zoomable / high quality (optional)

Every diagram MUST have a PNG export.

---

Adding a Diagram (Required Workflow)

1. Create or edit the diagram in draw.io
2. Save the .drawio file into diagrams/<category>/
3. Export a .png (and optional .svg)
4. Commit all files to Git

If a diagram cannot be viewed without draw.io running, it is not complete.

---

Embedding Diagrams in Wiki.js Pages

Always embed PNG or SVG, never live editors.

Example:

![Core Network Diagram](../../diagrams/network/core.png)

_Source file: core.drawio_

This ensures:

• Fast rendering
• Offline viewing
• No service dependency

---

Git Workflow Expectations

Authoring:

• All pages are created and edited in Wiki.js
• Wiki.js commits changes automatically

Offline Access:

• Documentation is read directly from the Git clone
• Markdown and images must be sufficient without Wiki.js

What Not To Do:

• Do not create wiki pages directly in Git
• Do not rename paths outside Wiki.js
• Do not store diagrams only inside draw.io

---

Lab-Down Access Model

When the lab is unavailable:

1. Open the local Git clone
2. Read README.md
3. Navigate to emergency/
4. View diagrams via .png files
5. Execute recovery steps

No services are required.

---

README.md (Recommended Content)

The root README.md should contain:

• Purpose of the documentation
• Where to start during an outage
• Link list to emergency procedures
• High-level architecture notes

---

Final Notes

This structure is designed to:

• Scale cleanly
• Survive outages
• Remain readable for years
• Support automation and GitOps workflows

If documentation cannot be read when the lab is down, it is incomplete.

This structure makes that impossible.