Obsidian HUGO Git Workflow

calendar May 15, 2025 · 3 min read · obsidian Hugo git  ·
Share on: linkedin copy

Prerequisites

This tutorial shows how the work flow on how to create content in obsidian git and hugo and have it available on git pages wit minimal scripting

The following are the prerequisites

  • git
  • hugo
  • obsidian (optional)

Github pages

This workflow can be achieved without obsidian. However, having obsidian greatly helps with visualizing your markdown before it is committed to the website.

In order to use git pages you first need to create a git repo with the following exact name.

1<username>.github.io

This repo is reserved for git hub pages. to test it you can put a boiler plate index .html file in there. and navigate to the site

Hugo Setup

  • install Hugo based on your system instructions
  • create a Hugo site
  • Choose and template and install it based on the template instructions

Hugo Obsidian integration

To easily move content between Obsidian and Hugo I simply created a symbolic link between the Hugo Content folder and Obsidian. This ensured that any markdown updates I make in Obsidian are immediately reflected in Hugo without the need of any code. The key thing is to keep your drafts in post until you feel they are ready to be published

The following are the key steps: -

  • create the post in the post folder with draft version
  • Create your post content and unchecked draft
  • Please ensure that you set your baseurl in the hugo.toml file otherwise your page will not render well when pushed online

Posting content online

Huge creates web pages by compiling your markdown to html. This is done when the Hugo command is run. Hugo takes your markdown and converts it to html and places the html files in the public folder

[!note] I noticed that when i just run the Hugo command without the options it replaced my baseurl. As such i had to run it with the options below to ensure that my baseurl is not changed. If there is something I missed please share it in the comments below.

1hugo --baseURL=https://giftcp.github.io/

Each time the site is recompiled the static files in the public directory are updated or created. As such we need to re-upload them to git.

stage the files

1git add .

commit the changes

1git commit -m "new content"

Push the changes to the remote repo

1git push origin main

As you can see to maintain this workflow it only requires 4 lines of code that can be bundled into a single script.

1hugo --baseURL=https://giftcp.github.io/
2git add .
3git commit -m "new content" # a random function can usied to generete text for the commit messege
4git push origin main

Update Script

As stated above the public folder is a sub-module. To refresh the public folders the Hugo command needs to be ran in the root folder and the git commits need to be run from the the public folder. i designed this script so that it can be run from anywhere. You can modify it to suit your needs accordingly.

 1#!/bin/bash
 2
 3# === Configuration ===
 4SOURCE_DIR="$HOME/PARA/01 PROJECTS/hugo/clarity"
 5PUBLIC_DIR="$SOURCE_DIR/public"
 6GIT_DIR="$SOURCE_DIR/.git/modules/public"
 7BASE_URL="https://giftcp.github.io/"
 8
 9# Step 1: Compile the markdown to HTML in the submodule
10hugo --source "$SOURCE_DIR" --baseURL="$BASE_URL"
11
12# Step 2: Push changes inside the submodule
13git --git-dir="$GIT_DIR" --work-tree="$PUBLIC_DIR" add .
14
15COMMIT_MSG="Auto-update $(date +'%Y-%m-%d_%H-%M-%S')"
16git --git-dir="$GIT_DIR" --work-tree="$PUBLIC_DIR" commit -m "$COMMIT_MSG"
17
18git --git-dir="$GIT_DIR" --work-tree="$PUBLIC_DIR" push origin main

Coming Soon

the keenest of you would have noticed that i have not documented handling images. The following are some option i intend to use

  • A script to update the markdown image path
  • store the images online and map my obsidan image path online.

I like the second option i will share it in my next post