Runbook — Add Documentation

Step-by-step process for adding a new page to this Docusaurus site.

Prerequisites

• WireGuard connected (Vera → Helsinki2)
• Node.js installed on Vera (node --version)
• SSH access: [email protected] (Proxmox) and [email protected] (VM700)

Step 1 — Create the markdown file on Vera

cd /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman

Create a new .md file in the appropriate docs/ subdirectory:

# Example: adding a new Helsinki2 page
nano docs/helsinki2/new-page.md

Frontmatter required at the top of every page:

---
id: new-page
title: My New Page Title
sidebar_position: 7
---

# My New Page Title

Content goes here...

The sidebar_position controls order within the section. Use the next available number.

Step 2 — Add to sidebars.js

Open sidebars.js and add the page id to the correct section:

nano sidebars.js

Find the relevant sidebar category (e.g. helsinki2Sidebar) and add the new page id:

items: [
  'helsinki2/proxmox-overview',
  'helsinki2/ct-and-vm-inventory',
  'helsinki2/new-page',   // ← add here
],

Step 3 — Build on Vera

cd /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman
npm run build

Confirm the build succeeds with [SUCCESS] Generated static files in "build".

Fix any broken link warnings before deploying.

Step 4 — Deploy to VM700

Run both rsync steps from the Proxmox host ([email protected]):

# Pull build from Vera to Proxmox
rsync -avz --delete \
  [email protected]:'/home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman/build/' \
  /tmp/docsaurus-build/

# Push from Proxmox to VM700
rsync -avz --delete \
  /tmp/docsaurus-build/ \
  [email protected]:/opt/stacks/echohuman-docsaurus/site-build/

No container restart needed. nginx serves static files directly from site-build/.

Step 5 — Verify

curl -I https://docsaurus.echohuman.org
curl -s https://docsaurus.echohuman.org/helsinki2/new-page | grep '<title>'

Troubleshooting

Problem	Cause	Fix
New page not appearing in sidebar	ID missing from sidebars.js	Add the page id and rebuild
Build fails with broken link	A link references a non-existent page	Fix the link or set onBrokenLinks: 'warn'
Public URL shows old content	Browser cache	Hard refresh (Ctrl+Shift+R) or test with curl
site-build has old content after rsync	Rsync ran before build finished	Re-run rsync after build completes