Jekyll에서 Hugo로의 마이그레이션 가이드
Jekyll에서 Hugo로 마이그레이션을 결심한 뒤, 많은 문서를 참고하면서도 생각보다 시행착오를 꽤 겪었습니다. 단순히 정적 사이트 생성기를 바꾸는 게 아니라, 생태계와 철학 자체가 다른 도구로 이동하는 일이었기 때문입니다.
이 글은 저처럼 Jekyll을 쓰다 Hugo로 옮기고자 하는 분들을 위해, 제가 직접 경험한 내용을 바탕으로 정리한 실전 마이그레이션 가이드입니다. 각 단계에서의 의사결정과 구체적인 명령어, 주의할 점까지 담았으니 참고가 되면 좋겠습니다.
✅ 마이그레이션 전에 알아야 할 것
Jekyll과 Hugo는 모두 정적 사이트 생성기(SSG)이지만, 몇 가지 핵심적인 차이점이 있습니다:
| 항목 | Jekyll (Ruby 기반) | Hugo (Go 기반) |
|---|---|---|
| 빌드 속도 | 게시물 수가 많아질수록 급격히 느려짐 | 수백 개 이상 포스트도 수 초 내 빌드 가능 |
| 설치 방식 | Ruby, Gem, Bundler 등 의존성 필요 | 단일 바이너리 (설치 즉시 사용 가능) |
| 기능 확장 | 플러그인 기반 (GitHub Pages에선 제한적) | 내장 기능 중심 (Shortcodes, 이미지 처리 등) |
| 설정 파일 | _config.yml | hugo.toml, hugo.yaml, hugo.json 모두 지원 |
| 템플릿 언어 | Liquid | Go 템플릿 엔진 |
1️⃣ 마이그레이션 사전 준비
🔍 기존 Jekyll 블로그 파악
_config.yml과Gemfile에서 사용 중인 설정과 플러그인을 정리합니다._layouts,_includes,_posts,_data등의 디렉터리 구조도 미리 파악해 둡니다.
💾 Hugo 설치
macOS:
BASHbrew install hugoWindows:
BASHwinget install Hugo.Hugo.Extended
주의: SCSS 등 스타일을 커스터마이징할 계획이라면 Extended 버전을 설치해야 합니다.
📁 새 Hugo 프로젝트 생성
hugo new site my-hugo-blog
cd my-hugo-blog
git init2️⃣ 콘텐츠 이전
📦 Jekyll 포스트 가져오기
Hugo는 기본적으로 Jekyll import 기능을 제공합니다.
hugo import jekyll /path/to/old-jekyll-site이 명령어는 _posts 폴더의 .md 파일들을 content/posts/로 옮기고, assets, images 등의 정적 리소스를 static/ 폴더로 복사합니다.
🛠 Front Matter 정리
가장 많이 시간을 쏟았던 부분입니다.
url:필드 제거 → Hugo의 퍼머링크 설정과 충돌하므로 모두 삭제해야 합니다.date:포맷 통일 →YYYY-MM-DD형식으로 맞춰주는 것이 Hugo 테마들과 잘 호환됩니다.tags,categories를 배열 형태로 변환YAMLtags: ["LLM", "Compiler"]
🖼 이미지 경로 수정
Hugo는 static/ 폴더 아래의 리소스를 루트(/) 경로로 사용합니다.
예: static/images/foo.png → /images/foo.png
3️⃣ 테마 선택 및 적용
Hugo는 정말 많은 테마를 제공합니다. 직접 themes.gohugo.io에서 살펴보며 테스트해보시는 걸 추천드립니다.
저는 다음 조건을 중요하게 봤습니다:
- 디자인 완성도
- 최근 커밋 여부 (유지보수 상태)
- 기본 기능 (다크 모드, 댓글, SEO 등) 포함 여부
👉 최종적으로 저는 hugo-narrow 테마를 선택했습니다. 시작한 지 오래되진 않았지만, 저의 사용 목적과 잘 맞았고 디자인도 만족스러웠습니다.
테마 적용 방법 (Git Submodule 방식)
git submodule add https://github.com/<theme-repo> themes/narrow
echo 'theme = "narrow"' >> hugo.toml4️⃣ URL 구조 유지 (SEO)
기존 블로그가 검색 엔진에 노출되어 있었다면 URL 구조를 유지하는 것이 매우 중요합니다.
[permalinks]
posts = "/:year/:month/:slug/"그리고 각 마크다운 파일에 아래 필드를 추가하세요:
slug: my-awesome-post이렇게 하면 2023/08/my-awesome-post/ 같은 경로로 빌드됩니다.
5️⃣ 빌드 및 배포
🔄 로컬 서버 확인
hugo server -D-D는 draft 상태인 글도 포함해서 보여줍니다.- 브라우저에서
http://localhost:1313로 접속해 확인하세요.
🚀 GitHub Pages로 배포
Hugo는 GitHub Actions 워크플로를 이용해 자동 배포가 가능합니다. 다음 템플릿을 참고하면 쉽게 설정할 수 있습니다:
또는 Netlify, Cloudflare Pages, Vercel 등에서 더 간편하게 배포할 수도 있습니다.
마치며
Hugo로의 마이그레이션은 저에게 있어 단순한 기술 교체 이상의 경험이었습니다. 속도, 구조, 관리 편의성 모든 면에서 만족스럽고, 블로그에 더 집중할 수 있는 환경이 된 것 같아 매우 만족스럽습니다.
혹시 지금 Jekyll을 쓰고 있고, 느린 빌드나 유지보수 문제로 고민 중이시라면 한 번쯤 Hugo를 고려해보시길 추천드립니다. 생각보다 훨씬 수월하게 옮겨올 수 있습니다!
댓글