Hugo BlowFish로 나만의 블로그 만들기#
정적 사이트 생성기로 블로그를 만들어보고 싶다는 생각, 한 번쯤은 해보셨죠? 저도 그랬어요! WordPress는 너무 무겁고, Jekyll은 뭔가 복잡하고… 그러다 Hugo를 알게 되었고, 특히 BlowFish 테마가 정말 마음에 들더라고요. 🎯
이번 글에서는 제가 실제로 이 블로그를 만들면서 겪은 모든 시행착오와 해결 과정을 공유해드릴게요. Windows에서 IntelliJ로 개발하고, Linux 서버에 Docker로 배포하는 전 과정을 담았습니다.
왜 Hugo + BlowFish를 선택했을까?#
블로그 플랫폼을 고민하다가 Hugo를 선택한 이유:
- 빠른 빌드 속도 - 몇 초만에 사이트 전체 생성
- Markdown 기반 - 개발자에게 익숙한 문법
- 정적 파일 - 서버 부담 없이 빠른 로딩
- 무료 호스팅 - GitHub Pages, Netlify 등 다양한 옵션
그 중에서도 BlowFish 테마는:
- 깔끔한 디자인 - Tailwind CSS 기반의 모던한 UI
- 다크모드 지원 - 개발자 친화적 😎
- 풍부한 기능 - 태그, 시리즈, 검색 등 블로그에 필요한 모든 기능
- 활발한 업데이트 - 지속적인 개선과 버그 수정
1. Hugo 설치하기 - Windows 환경#
처음엔 Chocolatey로 설치하려다가 권한 문제로 고생했어요. 결국 Winget으로 해결했습니다!
추천 방법: Winget 사용#
# Windows 10/11에서 기본 제공되는 패키지 매니저
winget install Hugo.Hugo.Extended
대안 방법들#
# Chocolatey 사용 (관리자 권한 필요)
choco install hugo-extended
# 직접 다운로드
# https://github.com/gohugoio/hugo/releases에서
# hugo_extended_x.x.x_windows-amd64.zip 다운로드
꿀팁: Hugo 명령어가 인식되지 않으면 IntelliJ를 재시작해보세요. PATH 설정이 바로 적용되지 않을 수 있어요.
2. 새 블로그 프로젝트 생성#
# 블로그 프로젝트 폴더 생성
hugo new site my-awesome-blog
cd my-awesome-blog
# Git 저장소 초기화 (테마 설치에 필요)
git init
IntelliJ에서 이 폴더를 열면 Hugo 프로젝트 구조를 한눈에 볼 수 있어요. 저는 개발할 때 IntelliJ의 터미널을 주로 사용했어요.
3. BlowFish 테마 설치 - 이게 핵심!#
여기서부터가 진짜 시작이에요. 공식 문서대로 따라해도 안 되는 부분들이 있더라고요.
3-1. 테마 다운로드#
# Git submodule로 테마 추가 (추천 방식)
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
3-2. 설정 파일 복사 (중요!)#
# config 폴더 구조 생성
mkdir -p config/_default/languages
# 테마의 기본 설정 파일들을 프로젝트로 복사
cp themes/blowfish/config/_default/* config/_default/
cp themes/blowfish/config/_default/languages/ko.toml config/_default/languages/
여기서 실수하기 쉬운 부분: 설정 파일을 복사하지 않고 바로 시작하면 기본 Hugo 테마처럼 밋밋하게 나와요. 꼭 복사해주세요!
4. 핵심 설정하기#
4-1. 기본 사이트 설정#
config/_default/config.toml
파일을 열어서:
baseURL = "https://yourdomain.com" # 실제 도메인으로 변경
languageCode = "ko"
title = "내 블로그" # 임시 제목 (실제로는 languages.ko.toml에서 설정)
theme = "blowfish"
# Google Analytics (나중에 설정)
[services]
[services.googleAnalytics]
id = "G-XXXXXXXXXX"
4-2. 한국어 설정 (가장 중요!)#
여기서 큰 함정이 있어요! config.toml
의 title은 실제로 표시되지 않습니다. 진짜 제목은 languages.ko.toml
에서 설정해야 해요.
# 한국어 설정 파일 생성
cp config/_default/languages.en.toml config/_default/languages.ko.toml
cp config/_default/menus.en.toml config/_default/menus.ko.toml
config/_default/languages.ko.toml
:
languageCode = "ko"
languageName = "한국어"
displayName = "KO"
isoCode = "ko"
weight = 1
rtl = false
title = "CoderRed의 개발 블로그" # 실제 헤더에 표시되는 제목!
dateFormat = "2006년 1월 2일"
[author]
name = "CoderRed"
image = "images/author.jpg"
headline = "개발자의 기록과 성장 이야기"
bio = "백엔드 개발자이자 기술 탐험가입니다. 배우고 경험한 것들을 기록하며 공유합니다."
links = [
{ email = "mailto:[email protected]" },
{ github = "https://github.com/yourusername" },
{ twitter = "https://twitter.com/yourusername" }
]
4-3. 메뉴 설정#
config/_default/menus.ko.toml
:
# 상단 네비게이션
[[main]]
name = "홈"
pageRef = "/"
weight = 10
[[main]]
name = "포스트"
pageRef = "/posts"
weight = 20
[[main]]
name = "태그"
pageRef = "/tags"
weight = 30
[[main]]
name = "시리즈"
pageRef = "/series"
weight = 35
[[main]]
name = "소개"
pageRef = "/about"
weight = 40
# 하단 푸터 메뉴
[[footer]]
name = "개인정보처리방침"
pageRef = "/privacy"
weight = 10
[[footer]]
name = "연락처"
pageRef = "/contact"
weight = 20
5. 첫 번째 포스트 작성해보기#
드디어 글을 써볼 시간이에요!
# 새 포스트 생성 (Bundle 형태로)
hugo new posts/my-first-post/index.md
생성된 content/posts/my-first-post/index.md
파일:
---
title: "Hugo BlowFish로 블로그 시작하기"
date: 2025-09-04T17:30:00+09:00
draft: false
author: "CoderRed"
description: "Hugo와 BlowFish 테마로 만든 첫 번째 포스트입니다."
tags: ["Hugo", "BlowFish", "블로그", "시작"]
categories: ["블로그"]
series: ["블로그 시작하기"]
showToc: true
---
# 안녕하세요! 👋
Hugo와 BlowFish 테마로 만든 첫 번째 포스트입니다.
## 왜 Hugo를 선택했나요?
정적 사이트 생성기 중에서 Hugo를 선택한 이유는...
- **빠른 속도** ⚡
- **간편한 설정** ⚙️
- **풍부한 테마** 🎨
- **Markdown 지원** 📝
## 앞으로의 계획
앞으로 이 블로그에서는 다음과 같은 내용들을 다룰 예정입니다:
1. 개발 경험담
2. 기술 학습 노트
3. 프로젝트 회고
4. 일상 이야기
함께 성장해나가요! 🚀
6. 로컬에서 확인해보기#
# 개발 서버 시작 (드래프트 포함)
hugo server -D
# 브라우저에서 http://localhost:1313 접속
짜잔! 🎉 블로그가 나타났나요? 처음 보는 순간의 그 감동이란…
7. 자주 만나는 문제들과 해결법#
실제로 설정하면서 만났던 문제들이에요:
7-1. Hugo 버전 호환성 문제#
Error: BlowFish theme requires Hugo version 0.141.0 or higher
해결법: 최신 Extended 버전으로 업데이트
winget upgrade Hugo.Hugo.Extended
7-2. “paginate deprecated” 경고#
# config/_default/config.toml에서
# 기존: paginate = 10
# 변경:
[pagination]
pagerSize = 10
7-3. 템플릿 함수 오류#
Error: template function "try" not defined
해결법:
# Hugo 캐시 정리
hugo mod clean --all
# 서버 재시작
hugo server -D --disableFastRender
8. GitHub에 올리기#
로컬에서 잘 돌아간다면 이제 GitHub에 올려봅시다!
8-1. .gitignore 설정#
# Hugo 관련
public/
resources/_gen/
.hugo_build.lock
# IDE 관련
.idea/
.vscode/
# 기타
.DS_Store
Thumbs.db
8-2. GitHub 저장소 생성 및 푸시#
# 파일 추가
git add .
git commit -m "Initial commit: Hugo BlowFish 블로그 설정"
# GitHub 저장소 연결 (SSH 권장)
git remote add origin [email protected]:yourusername/your-blog.git
git branch -M main
git push -u origin main
GitHub SSH 키 설정 팁: 처음에 HTTPS로 했다가 토큰 인증 문제로 고생했어요. SSH 키 설정하는 게 훨씬 편해요!
9. 서버 배포하기 (Docker 사용)#
로컬에서만 보기엔 아쉽죠? 이제 실제 서버에 배포해봅시다!
9-1. Hugo 빌드#
# 프로덕션용 빌드
hugo --minify --cleanDestinationDir
9-2. Docker로 배포#
# Nginx 컨테이너로 실행
docker run -d \
--name hugo-blog \
--restart unless-stopped \
-p 9572:80 \
-v ~/coderblog/public:/usr/share/nginx/html:ro \
nginx:alpine
9-3. 자동 배포 스크립트#
매번 수동으로 배포하기 귀찮으니까 스크립트를 만들어봤어요:
#!/bin/bash
# deploy.sh
echo "🚀 블로그 배포 시작..."
cd ~/coderblog
git pull origin main
echo "📦 Hugo 빌드 중..."
hugo --minify --cleanDestinationDir
echo "🐳 Docker 컨테이너 재시작..."
docker stop hugo-blog 2>/dev/null || true
docker rm hugo-blog 2>/dev/null || true
docker run -d \
--name hugo-blog \
--restart unless-stopped \
-p 9572:80 \
-v ~/coderblog/public:/usr/share/nginx/html:ro \
nginx:alpine
echo "✅ 배포 완료! https://coderred.com"
10. 유용한 Hugo 명령어들#
개발하면서 자주 사용하는 명령어들이에요:
# 새 포스트 생성 (Bundle 형태)
hugo new posts/post-name/index.md
# 새 페이지 생성
hugo new about/index.md
# 드래프트 포함해서 서버 실행
hugo server -D
# 미래 날짜 포스트도 포함해서 빌드
hugo -F
# 특정 환경으로 빌드
hugo --environment production
# 사이트 통계 확인
hugo list all
마무리하며#
드디어 나만의 블로그가 완성되었네요! 🎉
처음엔 복잡해 보였지만, 차근차근 따라하다 보면 생각보다 어렵지 않아요. 특히 BlowFish 테마는 정말 잘 만들어진 것 같아요. 기능도 풍부하고 디자인도 깔끔하고!
앞으로의 계획:
- GitHub Actions로 자동 배포 설정
- Google Analytics 연동
- 댓글 시스템 추가 (Giscus)
- 검색 기능 활성화
- SEO 최적화
블로그를 시작하는 것은 첫 발걸음일 뿐이에요. 이제 꾸준히 좋은 글들을 써나가는 게 진짜 시작이죠! 함께 성장해나가요! 🚀