---
title: Netgrimoire Documentation
description: How to create and use Netgrimoire Docs
published: true
date: 2026-02-03T02:54:56.444Z
tags: 
editor: markdown
dateCreated: 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:
```bash
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:
```markdown
![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.