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 Writing Layer)#

To ensure notes are mirrored across Mac Studio, MacBook Air, and iPad without using Git for the writing layer.

  • Backend: Self-hosted CouchDB (10.1.2.230) at obsidian-sync.mmmo.app.
  • Plugin: Self-hosted LiveSync.
  • Strategy: Only pages are live synced.
  • Transfer settings and plugins: Copy the .obisidan folder

Warning: Obsidian should not be running on source and destination

rsync -avzhI --delete --progress /Users/marc/Obsidian/Homelab/.obsidian/ marc@10.1.2.5:/Users/marc/Obsidian/Homelab/.obsidian

Copy the full vault

Warning: Obsidian should not be running on source and destination

rsync -avzh --progress /Users/marc/Obsidian/Homelab/ marc@10.1.2.5:/Users/marc/Obsidian/Homelab/

2. The Content Bridge (Mac to Linux)#

1. Mac OS Script#

This script “beams” your notes from your Mac Studio to the Proxmox Hugo VM.

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

note: A copy of the script is also at /Volumes/Software/Software/Scripts/MacOS/

#run manually vian the command push or: 
bash /Users/marc/Scripts/sync-obsidian-homelab-hugo.sh
cat /Users/marc/Scripts/sync-obsidian-homelab-hugo.log
# Create a push alias
echo "alias push='bash /Users/marc/Scripts/sync-obsidian-homelab-hugo.sh'" >> ~/.zshrc
source ~/.**zshrc**

Mac Studio Schedule#

# Mac Studio Schedule
crontab -e
10 12 * * * bash /Volumes/Software/Software/Scripts/MacOS/sync-obsidian-homelab-hugo.sh > /dev/null 2>&1
10 20 * * * bash /Volumes/Software/Software/Scripts/MacOS/sync-obsidian-homelab-hugo.sh > /dev/null 2>&1

3. The Git Publisher (Linux to Web)#

HP1Docker hosts the files, a script pushes the received notes from the VM to GitHub to trigger Cloudflare.

Location: /mnt/Software/Software/Scripts/Linux/

# Run script manually from 10.1.2.202 (HP1Proxmox)
bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh
tail -f /home/marc/hugo/homelab/logs/publish-hugo-homelab.log
# Create a push alias
echo "alias push='bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh && tail -f /home/marc/hugo/homelab/logs/publish-hugo-homelab.log'" >> ~/.bashrc

Proxmox VM Schedule#

# HP1Docker cron job
crontab -e
15 12 * * * bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh
15 20 * * * bash /mnt/Software/Software/Scripts/Linux/publish-hugo-homelab.sh

Warning: You need to close the terminal session and reopen a new one for the alias to take effect

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#

  1. Launch Obsidian.
  2. Select “Open folder as vault”.
  3. Navigate to and select /Users/marc/Obsidian/Homelab.
  4. 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.
Backward Obsidian Ollama & Stable Diffusion AI Guide Forward