deploy-vps.sh runs these steps in order — any failure before Hugo aborts the deploy without touching the live trees:

1. Validate TASKS.md (~/scripts/validate-tasks.sh) — structural check, abort on error.
2. Validate skills (~/scripts/validate-skills.sh) — every SKILL.md frontmatter parses.
3. Regenerate BEE_HUB_INDEX.md (scripts/build-index.py) — walks content/, emits the ~76 KB greppable map at ~/Sync/ED/BEE_HUB_INDEX.md. Also writes content/recent/_index.md with the 40 most recently-edited pages, sorted by mtime descending.
4. Refresh the home-page status block (scripts/build-status.py) — reads ~/Sync/ED/.homelab-snapshot.json, TASKS.md, the doc-sync logs, and the deploy log, then patches the <!-- STATUS-START -->/<!-- STATUS-END --> block in content/_index.md with current state (last deploy, briefing freshness, doc-sync status, active task count, ZFS pool capacities, container counts).
5. Build Ed’s dashboard (content/ed/build-ed-page.sh) — pulls latest briefing + diary + active tasks into content/ed/_index.md.
6. Hugo build in strict mode (--panicOnWarning --printPathWarnings) — aborts deploy on any error (unclosed shortcode, frontmatter parse, missing partial). Previous stale public/ survives if the new build fails.
7. Pagefind indexes public/ into public/pagefind/ — drives the search box in the top-right.
8. rsync to VPS + CT103 — only if all the above succeeded.

• Frontmatter: title: required; subtitle: if it’s a section landing; page_links: for top-of-page nav (label + url, plus external: true for off-site).
• Sidebar: sections use sidebar_sections: for a flat list, or sidebar_groups: for categorized groups (each with title + items: [{url, name}]). The home page (/homelab/) demonstrates sidebar_groups.
• Section shortcode: wrap discrete content blocks in section shortcodes with an id and title. The id becomes the anchor; the title is what shows in the sidebar’s section list.
• Mermaid diagrams: fenced mermaid blocks render on the client. Use sparingly — see /homelab/architecture/ for an example.
• Taxonomies (new): tags: [foo, bar] and status: active|retired|planned in frontmatter generate /tags/<name>/ and /status/<name>/ index pages automatically. Opt-in per page.
• “Last substantive update”: file mtime lies (auto-commits, typo fixes bump it). When a page gets a real content change worth signaling, add a last_substantive_update: YYYY-MM-DD frontmatter field — future Recently Updated views can prefer that signal over mtime.

The site is deployed to two places from the same source tree. Each is independently reachable:

Deployment is one command and updates both in sequence. If one target is unreachable (VPS routing is occasionally flaky), the other still updates.

cd ~/Sync/ED/homelab/bee_hub
bash deploy-vps.sh

What it does:

1. hugo --quiet builds the static site into public/
2. tar czf - public/ streams the build to each target
3. Extracts to /var/www/bee-hub/ on each host
4. Logs to ~/Library/Logs/bee-hub-deploy.log

Automatic deploys: cron runs the script every 30 minutes.

*/30 * * * * /Users/bee/Sync/ED/homelab/bee_hub/deploy-vps.sh

Targets are configured in the script at TARGETS=(...). To add a new target, add user@host:/path to the array. SSH keys are pre-shared via ~/.ssh/id_ed25519.

All content is plain Markdown with YAML frontmatter. Edit any _index.md file and save. The next deploy (manual or the 30-min cron) ships the change to both live hosts.

A persistent Hugo dev server runs on the Mac Studio via launchd, providing live-preview at all times (rebuilds within ~1s on save):

This is separate from the deployed versions at hub.edmd.me and troglodyteconsulting.com. Use it for active authoring and verification; deploy-vps.sh pushes to production.

# Restart the local preview server
launchctl kickstart -k gui/$(id -u)/com.bee.hugo-beehub

# Check status
launchctl print gui/$(id -u)/com.bee.hugo-beehub

# View logs
tail -f /tmp/hugo-beehub.log

Every page is a directory containing an _index.md file. The top-level nav is defined in hugo.toml:

Content tree (homelab section example):

content/homelab/
├── _index.md              — Category landing (sidebar list)
├── proxmox/_index.md      — Proxmox VE reference
├── services/_index.md     — Services directory
├── music-pipeline/_index.md
├── life-archive/_index.md
├── mcp-servers/_index.md
├── bee-hub/_index.md      — This page
└── shelfmark/_index.md

Category landing page — has a sidebar with sub-page links:

title: "Homelab"
subtitle: "Infrastructure, services, and remote access"
sidebar_sections:
  - { url: "/homelab/proxmox/", name: "Proxmox VE" }
sidebar_links:
  - { name: "External Link", url: "https://example.com" }

Individual page — has quick-access link buttons at top:

title: "Music Pipeline"
page_links:
  - { label: "Lidarr", url: "http://192.168.8.100:8686", external: true }
  - { label: "Internal Link", url: "/homelab/services/", external: false }

The bee-theme provides shortcodes for structuring content. All shortcode files live in themes/bee-theme/layouts/shortcodes/.

The app-card shortcode supports a docs parameter that renders a 📖 Docs ↗ link directly on the card — already used throughout the Mac Apps pages.

Edit an existing page: Open content/section/page/_index.md in any editor (BBEdit, VS Code, Obsidian). Hugo hot-reloads within ~1 second.

Add a new page:

mkdir -p ~/Sync/ED/homelab/bee_hub/content/homelab/new-page
# Create _index.md with frontmatter and content
# Add to parent _index.md sidebar_sections list

Add a new nav tab:

1. Create content/new-section/_index.md
2. Add entry to hugo.toml with a name, url, and weight
3. Restart the Hugo service — menu changes need a restart, content changes do not

Can I edit in Obsidian? Yes — all Hugo content is plain Markdown. Open ~/Sync/ED/homelab/bee_hub/content/ as an Obsidian vault. The YAML frontmatter block must stay intact. Hugo shortcodes show as raw text in Obsidian’s preview but edit safely.

For day-to-day edits, deploy-vps.sh handles builds automatically.

To regenerate the static /public/ folder without deploying:

cd ~/Sync/ED/homelab/bee_hub
hugo
# Output goes to /public/