Hugo is a static site generator — it reads Markdown files from content/ and produces a complete HTML site. The dev server watches for file changes and rebuilds automatically, so editing any _index.md shows up in the browser within a second.

Hugo runs as a persistent launchd agent that starts at login and restarts automatically if it crashes.

Service commands:

# Check status
launchctl list | grep hugo

# Stop
launchctl unload ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# Start
launchctl load ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# Restart
launchctl unload ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist && \
launchctl load ~/Library/LaunchAgents/com.beedifferent.hugo-hub.plist

# View logs
tail -50 ~/Library/Logs/hugo-hub.log
tail -20 ~/Library/Logs/hugo-hub.err.log

Note: Hugo’s dev server caches hugo.toml. Changes to the menu (adding/removing nav tabs) require a service restart to appear. Content changes (_index.md files) hot-reload automatically.

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.

The dev server serves content dynamically — no build step needed for day-to-day editing.

To regenerate the static /public/ folder:

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

The /public/ folder is included in the Mac Studio SYNC directory and gets pulled to Proxmox /nvmepool/sync/ by the nightly sync-mac.sh rsync job.