Obsidian + Hugo + GitHub Pages Blog Setup Guide

Overview

This setup creates an automated blog workflow where you write in Obsidian, push to GitHub, and GitHub Actions automatically builds and deploys your Hugo site.

Phase 1: Local Setup

Step 1: Install Required Tools

Install Hugo

# Windows (using Chocolatey)
choco install hugo-extended

# macOS (using Homebrew)
brew install hugo

# Linux (using Snap)
sudo snap install hugo

Install Git (if not already installed)
- Download from git-scm.com
Install Obsidian
- Download from obsidian.md

Step 2: Create Your Hugo Site

Generate Hugo site
```
hugo new site my-blog
cd my-blog
```
Initialize Git repository
```
git init
git branch -m main
```

Choose and install a Hugo theme

# Example with PaperMod theme
git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

# Or clone without submodule (simpler for beginners)
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

Step 3: Configure Hugo

Edit hugo.toml (or config.toml)

baseURL = 'https://yourusername.github.io/your-repo-name'
languageCode = 'en-us'
title = 'My Blog'
theme = 'PaperMod'

[params]
author = "Your Name"
description = "My awesome blog"

[menu]
[[menu.main]]
name = "Home"
url = "/"
weight = 10

[[menu.main]]
name = "Posts"
url = "/posts/"
weight = 20

Create content structure

mkdir -p content/posts
mkdir -p static/images

Phase 2: Obsidian Integration

Step 4: Setup Obsidian Vault

Create Obsidian vault in Hugo content directory
- Open Obsidian
- Choose “Open folder as vault”
- Select your my-blog/content folder
Configure Obsidian settings
- Go to Settings → Files & Links
- Set “Default location for new notes” to posts/
- Set “New link format” to “Relative path to file”
- Enable “Use [[Wikilinks]]” if you want internal linking

Step 5: Create Obsidian Templates

Create templates folder

content/
├── posts/
└── templates/
    └── blog-post.md

Blog post template (content/templates/blog-post.md)

---
title: "{{title}}"
date: {{date}}
draft: false
tags: []
categories: []
description: ""
---

# {{title}}

Your content here...

Configure Obsidian Templates plugin
- Go to Settings → Core plugins → Enable “Templates”
- Set template folder to templates

Phase 3: GitHub Setup

Step 6: Create GitHub Repository

Create new repository on GitHub
- Name: your-blog or yourusername.github.io
- Make it public
- Don’t initialize with README (you already have local repo)

Connect local repo to GitHub

git remote add origin https://github.com/yourusername/your-repo-name.git

Step 7: Create GitHub Actions Workflow

Create workflow directory
```
mkdir -p .github/workflows
```

Create deployment workflow (.github/workflows/deploy.yml)

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["master"] #or main 
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3

      - name: Build with Hugo
        env:
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Phase 4: GitHub Pages Configuration

Step 8: Enable GitHub Pages

Push your code first

git add .
git commit -m "Initial blog setup"
git push -u origin main

Configure GitHub Pages
- Go to your repo → Settings → Pages
- Source: “GitHub Actions”
- The workflow will automatically deploy after the first push

Phase 5: Content Creation Workflow

Step 9: Daily Workflow

Writing in Obsidian
- Open Obsidian vault (your Hugo content folder)
- Create new note in posts/ folder
- Use your blog post template
- Write your content using Markdown

Hugo-specific front matter

---
title: "My First Post"
date: 2024-01-15T10:00:00Z
draft: false
tags: ["technology", "blogging"]
categories: ["tutorial"]
description: "Learn how to set up a blog with Hugo and Obsidian"
---

Publishing workflow

# Test locally (optional)
hugo server -D

# Commit and push
git add .
git commit -m "New post: My First Post"
git push

Phase 6: Advanced Configuration

Step 10: Optimize Obsidian for Hugo

Install useful Obsidian plugins
- Templater (advanced templates)
- Obsidian Git (auto-sync)
- Tag Wrangler (manage tags)
Configure Obsidian Git plugin
- Auto-pull: every 10 minutes
- Auto-backup: every 10 minutes
- This automates the git workflow

Step 11: Hugo Customizations

Add image handling

# In your posts, reference images like:
![Alt text](../static/images/my-image.jpg)

Configure Hugo for Obsidian links
- Install Hugo modules or use shortcodes for better wiki-link support

Troubleshooting Tips

Common Issues

Theme not showing: Ensure theme is properly installed and referenced in config
Images not displaying: Check image paths and Hugo static folder structure
Build fails: Check Hugo version compatibility with your theme
Obsidian links: Some Obsidian-specific syntax may need conversion for Hugo

Useful Commands

# Test locally
hugo server -D

# Build site
hugo

# Check Hugo version
hugo version

# Create new post
hugo new posts/my-new-post.md

Benefits of This Setup

✅ Write naturally in Obsidian with all its features
✅ Automatic deployment when you push changes
✅ Version control for all your content
✅ Fast, static site performance
✅ Free hosting on GitHub Pages
✅ Mobile editing possible through Obsidian mobile + GitHub

Your blog will be live at https://yourusername.github.io/your-repo-name after the first successful deployment!