Homelab: Obsidian to Hugo Automated Publishing Guide#

This guide outlines the infrastructure and configuration required to sync an Obsidian vault across multiple devices and automate the publishing process to a Hugo website via Cloudflare Pages.

1. Multi-Device Sync (The Git & Web Layer)#

To sync your notes between computers and view them on mobile devices without the overhead of real-time database sync engines:

1.1. Between Computers (Mac Studio & MacBook Pro/Air)#

We use the Obsidian Git plugin to synchronize vaults directly via GitHub.

Repository: git@github.com:marcoue/obsidian-homelab.git
Shortcuts:
- Cmd + S: Commit & Push local changes to GitHub.
- Cmd + Shift + S: Pull remote changes from GitHub.
Settings:
- Auto-Pull: Vault pull interval is set to every 5 minutes, and pull updates on startup is enabled.
- Auto-Push: Vault backup interval is set to every 10 minutes to auto-commit and push in the background.

1.2. On Mobile Devices (iPhone & iPad)#

To avoid complex sync engines and conflict loops, Obsidian is not installed on mobile. Instead, notes are accessed via the browser using the self-hosted Hugo website:

Read Access: Simply browse your local Hugo web server instance. It provides instant, formatted, searchable access to all your notes with zero configuration, zero battery drain, and zero storage overhead on your phone/tablet.

2. The Content Bridge & Git Publisher (Mac to Web)#

The publishing pipeline is consolidated into a single master script run from your Mac Studio. It prepares a temporary Hugo-compatible copy of the notes, syncs that copy and the images to the Proxmox VM, triggers the Hugo build/deployment, and backs up your unchanged Obsidian vault to GitHub.

Location: /Users/marc/Scripts/MacOS/sync-obsidian-homelab-hugo.sh

A mirror copy of the script is also maintained at /Volumes/Software/Software/Scripts/MacOS/

2.1. Script Execution Workflow#

Running the script executes the following sequential steps:

Prepares Content: Copies Notes/ to a temporary staging directory at /tmp/homelab_hugo_sync/ and converts Obsidian same-page links, cross-note links, and image embeds into Hugo-compatible Markdown links and image paths. The original vault notes are not modified.
Syncs Content: Runs rsync to mirror the processed notes and Images/ to the Proxmox Hugo VM. The remote notes are placed in Hugo’s content/posts/ directory and images in static/images/.
Triggers Deploy: SSHs into the VM and runs the remote publication script (publish-hugo-homelab.sh), pushing built site changes to GitHub to trigger Cloudflare Pages.
Backs Up Vault: Git commits and pushes the original local Obsidian vault to GitHub (obsidian-homelab).

If any required step in the pipeline fails (e.g., the Proxmox VM is offline or unreachable), the script aborts immediately to prevent desynchronization. The temporary staging copy is recreated on each run and is not part of the Obsidian vault.

2.2. Command Usage#

Full Sync, Publish & Vault Backup (Default):

push
# (Alias for: bash /Users/marc/Scripts/MacOS/sync-obsidian-homelab-hugo.sh)

Sync-Only (No Build / No Git Backup):
```
push --sync-only
# or: push -s
```

2.3. Configuration & Alias Setup#

To configure the push alias on your Mac Studio:

# Add alias to ~/.zshrc
echo "alias push='bash /Users/marc/Scripts/MacOS/sync-obsidian-homelab-hugo.sh'" >> ~/.zshrc
source ~/.zshrc

2.4. Mac Studio Cron Schedule#

If you want automatic syncing and deployment on a schedule:

crontab -e

# Full publish & backup at 12:10 PM and 8:10 PM daily
10 12 * * * bash /Users/marc/Scripts/MacOS/sync-obsidian-homelab-hugo.sh > /dev/null 2>&1
10 20 * * * bash /Users/marc/Scripts/MacOS/sync-obsidian-homelab-hugo.sh > /dev/null 2>&1

3. The Remote Build Script (Linux VM)#

The remote Proxmox VM hosts the source files and publishes changes to the GitHub Hugo repo.

Location: /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh

You do not need to SSH to run this script manually anymore, as the Mac push script triggers it over SSH automatically. However, the VM cron schedule still runs independently as a backup.

3.1. Proxmox VM Cron Schedule#

# HP1Docker cron job
crontab -e

# Build and publish Hugo site at 12:15 PM and 8:15 PM daily
15 12 * * * bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh
15 20 * * * bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh

This section contains the old manual Git sync method. It is kept for reference only.

Archives - DO NOT USE#

1. Initial Software Installation.#

Install Hugo, & Git#
brew install hugo git
2. Pull Your Website Repository#

Ensure your SSH keys are added to the Mac, then clone directly into the target directory:
mkdir Obsidian
cd /Users/marc/Obsidian
git clone git@github.com:marcoue/Homelab.git
cd Homelab
3. Obsidian App Setup#

Launch Obsidian.

Select “Open folder as vault”.

Navigate to and select /Users/marc/Obsidian/Homelab.

All plugins (Git, numbering) and CSS will load automatically.

4. Obsidian Git Configuration (CRITICAL FOR SYNC)#

Manual Settings#

Auto intervals: All set to 0

Status bar display: Full (Ensures the numbers appear)

Show status bar: ON (Displays the 0-0 sync numbers)

Push on commit-and-sync: ON (Ensures work goes to GitHub)

Pull on commit-and-sync: ON

On Conflict: Manual

Hotkeys#

Git: Commit-and-sync: Cmd + S

Git: Pull: Cmd + Shift + S

5. Run Hugo website locally#

On MacStudio#
hugo server --bind 0.0.0.0 --baseURL http://10.1.2.4 --buildDrafts --disableFastRender --ignoreCache --noHTTPCache --gc -p 1313
On MacBook Air#
hugo server --bind 0.0.0.0 --baseURL http://10.1.2.5 --buildDrafts --disableFastRender --ignoreCache --noHTTPCache --gc -p 1313
if git errors when trying to pull#
# Force Git to overwrite your local local settings with the Mac Studio's version
git fetch --all
git checkout origin/main -- .obsidian/plugins/copilot/data.json
git commit -m "Align MacBook settings with Mac Studio"
6. Adding a new plugin to git for synching#

This is necessary in order to sync the plugin from MacStudio to MacBook Air (or reverse) Warning: Change the name of the folder with the one used by the plugin
# 1. Navigate to your main Homelab vault
cd "/Users/$(whoami)/Obsidian/Homelab"

# 2. Force add the plugin folder and its contents
# This overrides any .gitignore rules that are hiding your plugins
git add -f .obsidian/plugins/obsidian-icon-folder/

# 3. Commit and Push
git commit -m "Admin: Force sync Iconize plugin to GitHub"
git push
7. Hugo-Book: Force Alphabetical Sorting (A-Z)#

By default, the hugo-book theme sorts the sidebar (File Tree) by Weight, then Date (Newest First). This guide explains how to override the theme logic to use Alphabetical (Title) sorting instead, ensuring “Test 2” always stays above “Test 3” regardless of the creation date.

1. Create the Local Layout Override#

Instead of editing the theme files directly (which get overwritten during updates), we create a local copy in our project’s layouts folder. Hugo prioritizes files in the local layouts/ directory over the themes/ directory.

Run these commands on the VM:#
# 1. Create the target directory structure
mkdir -p /home/marc/hugo/homelab/layouts/_partials/docs/

# 2. Copy the theme's sidebar logic to your local layouts
cp /home/marc/hugo/homelab/themes/hugo-book/layouts/_partials/docs/menu-filetree.html /home/marc/hugo/homelab/layouts/_partials/docs/menu-filetree.html

# 3. Patch the sorting logic to use .ByTitle (Alphabetical)
sed -i 's/range (where .Section.Pages/range (where .Section.Pages.ByTitle/g' /home/marc/hugo/homelab/layouts/_partials/docs/menu-filetree.html
2. Clean and Rebuild#

After applying the patch, Hugo needs a “Clean” build to wipe the old sorting memory from its cache.
# Wipe temporary build files
rm -rf /home/marc/hugo/homelab/public /home/marc/hugo/homelab/resources

# Restart the Hugo server for testing
hugo server --bind 0.0.0.0 --baseURL "[http://10.1.2.202](http://10.1.2.202)" --buildDrafts --disableFastRender --ignoreCache --noHTTPCache --gc -p 1313
How it Works#

The Logic Change: We changed range .Section.Pages to range .Section.Pages.ByTitle.

The Result: Hugo now ignores the date: field in your Markdown frontmatter for sorting purposes. It looks strictly at the title: field.

The Tie-Breaker: If titles are identical, it falls back to the filename alphabetically.

Maintenance#

To Revert: Simply delete the file at /home/marc/hugo/homelab/layouts/_partials/docs/menu-filetree.html and Hugo will go back to the theme’s original date-based sorting.

New Notes: Your standard Templater template will now work perfectly without needing any manual weight or date hacks.