Obsidian으로 Hugo 블로그 운영하기: GitHub & Cloudflare 배포 가이드

이 가이드는 Obsidian을 사용하여 개인 블로그를 작성하고 관리하는 방법입니다. 로컬 환경에서 글을 작성하고, Hugo를 통해 정적 사이트를 생성한 후, GitHub와 Cloudflare Pages를 통해 무료로 배포하는 전체 과정을 다룹니다.

핵심 워크플로우

Obsidian (글 작성) → Hugo (사이트 생성) → GitHub (버전 관리) → Cloudflare Pages (배포)

왜 이 스택을 선택해야 하는가?

장점

• 완전한 데이터 소유권: 모든 콘텐츠가 로컬 마크다운 파일로 저장
• 무료 운영: 호스팅, 도메인(선택사항), CI/CD 모두 무료
• 빠른 성능: 정적 사이트의 장점으로 초고속 로딩
• 유연성: 언제든지 다른 플랫폼으로 이전 가능
• 버전 관리: Git을 통한 모든 변경사항 추적

단점 및 고려사항

• 초기 설정에 기술적 지식 필요
• 외부 서비스(GitHub, Cloudflare) 의존
• 댓글 등 동적 기능 구현 시 추가 서비스 필요

필요한 도구들

필수 도구

1. Obsidian: 마크다운 에디터
2. Hugo: 정적 사이트 생성기
3. Git: 버전 관리
4. GitHub 계정: 코드 저장소
5. Cloudflare 계정: 웹 호스팅

선택적 도구

• VSCode: 코드 편집기
• Front Matter CMS: VSCode 확장
• Algolia: 검색 기능
• Obsidian Publish: 대안적 배포 방법

상세 설정 가이드

1. Hugo 설치 및 설정

macOS

brew install hugo

Windows

choco install hugo -confirm

Linux

sudo snap install hugo

새 사이트 생성

hugo new site my-blog
cd my-blog

2. 테마 설정

Bear Blog 테마 추가

git init
git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog

config.toml 설정

baseURL = 'https://yourdomain.com/'
languageCode = 'ko-kr'
title = '나의 블로그'
theme = 'hugo-bearblog'

[params]
  description = "개인 블로그"
  favicon = "images/favicon.png"

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

3. Obsidian 연동

폴더 구조 설정

my-blog/
├── archetypes/
├── content/
│   └── blog/     # Obsidian vault로 설정할 폴더
├── data/
├── layouts/
├── static/
├── themes/
└── config.toml

Obsidian 설정

1. Obsidian 실행
2. "Open folder as vault" 선택
3. my-blog/content/blog 폴더 선택

Front Matter 템플릿 생성

Obsidian 템플릿 폴더에 blog-template.md 생성:

+++
title = "{{title}}"
date = {{date}}
tags = ["blog"]
draft = true
description = ""
+++

## 제목

내용을 여기에 작성하세요.

4. GitHub 리포지토리 설정

새 리포지토리 생성

# GitHub에서 리포지토리 생성 후
git remote add origin https://github.com/username/my-blog.git
git branch -M main

.gitignore 파일 생성

/public/
/resources/_gen/
.hugo_build.lock
.DS_Store

초기 커밋

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

5. Cloudflare Pages 설정

프로젝트 생성

1. Cloudflare 대시보드 접속
2. Pages 섹션 선택
3. "Create a project" 클릭
4. GitHub 연결 및 리포지토리 선택

빌드 설정

• Build command: hugo --minify
• Build output directory: public
• Environment variables
  • HUGO_VERSION: 0.119.0 (최신 버전 확인)

6. 자동 배포 워크플로우

GitHub Actions 설정 (선택사항)

.github/workflows/deploy.yml 생성

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        submodules: true
        fetch-depth: 0

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

    - name: Build
      run: hugo --minify

    - name: Deploy
      uses: cloudflare/pages-action@v1
      with:
        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        projectName: my-blog
        directory: public

워크플로우 최적화

1. 로컬 미리보기

실시간 미리보기 스크립트

preview.sh 생성

#!/bin/bash
hugo server -D --navigateToChanged

2. 자동화된 퍼블리싱

원클릭 배포 스크립트

publish.sh 생성

#!/bin/bash

# 드래프트 상태 변경
read -p "게시할 파일명 (확장자 제외): " filename
sed -i '' 's/draft = true/draft = false/' "content/blog/${filename}.md"

# Git 커밋 및 푸시
git add .
git commit -m "Publish: ${filename}"
git push origin main

echo "✅ 게시 완료! 1-2분 후 사이트에서 확인하세요."

3. 검색 기능 추가 (Algolia)

Algolia 설정

1. Algolia 계정 생성
2. 새 인덱스 생성
3. API 키 획득

인덱싱 스크립트

update-search-index.js

const algoliasearch = require('algoliasearch');
const fs = require('fs');
const matter = require('gray-matter');

const client = algoliasearch('YOUR_APP_ID', 'YOUR_ADMIN_KEY');
const index = client.initIndex('blog_posts');

// Hugo content 폴더 스캔 및 인덱싱
// ... (구현 코드)

4. 이미지 최적화

이미지 처리 스크립트

optimize-images.sh

#!/bin/bash

# WebP 변환
for img in static/images/*.{jpg,png}; do
  cwebp "$img" -o "${img%.*}.webp"
done

대안적 접근 방법들

1. VSCode + Front Matter CMS

VSCode를 주 편집기로 사용하는 방법

300x250

Front Matter 설정

.frontmatter/frontmatter.json

{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "blog",
      "pageBundle": false,
      "fields": [
        {
          "title": "Title",
          "name": "title",
          "type": "string"
        },
        {
          "title": "Publishing date",
          "name": "date",
          "type": "datetime"
        },
        {
          "title": "Draft",
          "name": "draft",
          "type": "boolean"
        }
      ]
    }
  ]
}

2. Obsidian Digital Garden 플러그인

직접 Obsidian에서 배포하는 방법

1. Digital Garden 플러그인 설치
2. GitHub 리포지토리 연결
3. 자동 배포 설정

3. 커스텀 Obsidian 플러그인

자체 배포 플러그인 개발

// main.js
module.exports = class MyPublishPlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: 'publish-to-blog',
      name: 'Publish to Blog',
      callback: () => this.publishToBlog()
    });
  }

  async publishToBlog() {
    // 현재 파일 가져오기
    const file = this.app.workspace.getActiveFile();
    // Front matter 수정
    // Git 커밋 및 푸시
  }
}

4. 다른 정적 사이트 생성기 사용

Jekyll (GitHub Pages 기본)

# _config.yml
title: My Blog
description: Personal Blog
theme: minima

Gatsby

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-plugin-markdown-pages',
    'gatsby-theme-blog'
  ]
}

Next.js

// next.config.js
module.exports = {
  output: 'export'
}

고급 팁과 트러블슈팅

1. 성능 최적화

Hugo 빌드 최적화

# config.toml
[build]
  writeStats = true

[minify]
  minifyOutput = true

Cloudflare 캐싱 규칙

• 정적 자산: 1년
• HTML: 1시간
• API 응답: 5분

2. SEO 최적화

구조화된 데이터

<!-- layouts/partials/structured-data.html -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "{{ .Title }}",
  "datePublished": "{{ .Date.Format "2006-01-02" }}"
}
</script>

3. 백업 전략

자동 백업 스크립트

#!/bin/bash
# backup.sh

# Obsidian vault 백업
tar -czf "backup-$(date +%Y%m%d).tar.gz" content/blog/

# 원격 저장소에 업로드
rclone copy backup-*.tar.gz remote:backups/

4. 문제 해결

빌드 실패

# Hugo 버전 확인
hugo version

# 서브모듈 업데이트
git submodule update --init --recursive

Cloudflare Pages 배포 실패

• 환경 변수 확인
• 빌드 로그 검토
• 노드 버전 지정

Obsidian 동기화 문제

• iCloud/Dropbox 충돌 해결
• .obsidian 폴더 제외

5. 모니터링 및 분석

Google Analytics 추가

<!-- layouts/partials/analytics.html -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>

Cloudflare Analytics

• 자동으로 제공되는 분석 데이터 활용
• Web Vitals 모니터링

보안 고려사항

1. API 키 관리

# .env.local (절대 커밋하지 않음)
ALGOLIA_ADMIN_KEY=xxx
CLOUDFLARE_API_TOKEN=xxx

2. 콘텐츠 보안 정책

# netlify.toml 또는 _headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"

비용 분석

무료 티어 한계

• GitHub: 무제한 공개 리포지토리
• Cloudflare Pages:
  • 월 500회 빌드
  • 무제한 대역폭
  • 커스텀 도메인 지원

유료 옵션

• Obsidian Publish: 월 $8
• 커스텀 도메인: 연 $10-15
• 추가 빌드: Cloudflare Pro 플랜

마이그레이션 가이드

다른 플랫폼으로 이전

1. Netlify로 이전

   # netlify.toml
   [build]
     command = "hugo --minify"
     publish = "public"

2. Vercel로 이전

   // vercel.json
   {
     "buildCommand": "hugo --minify",
     "outputDirectory": "public"
   }

3. 자체 호스팅

   # nginx.conf
   server {
     root /var/www/blog/public;
     index index.html;
   }

Obsidian + Hugo + GitHub + Cloudflare Pages 조합은 개발자 친화적이면서도 강력한 블로그 운영 방법입니다. 초기 설정은 다소 복잡할 수 있지만, 한 번 구축하면 매우 효율적인 워크플로우를 제공합니다.

핵심 포인트

• 로컬 우선 접근으로 데이터 소유권 보장
• 무료로 전문적인 블로그 운영 가능
• 유연한 확장성과 이전 가능성
• 빠른 성능과 우수한 SEO

추천 대상

• 기술적 지식이 있는 블로거
• 마크다운 작성을 선호하는 사용자
• 데이터 소유권을 중요시하는 사람
• 무료로 블로그를 운영하고 싶은 사람