Hugo는 Go 언어로 만들어진 빠른 정적 사이트 생성기로, PaperMod 테마와 함께 사용하면 깔끔하고 빠른 블로그를 쉽게 만들 수 있습니다. 이번 가이드에서는 Hugo 설치부터 PaperMod 테마 적용, GitHub 레포지터리 설정, Cloudflare Pages 배포, 그리고 커스텀 도메인 연결까지 전 과정을 단계별로 설명합니다.

Hugo란 무엇인가

Hugo는 세계에서 가장 빠른 정적 사이트 생성기 중 하나입니다. Markdown으로 콘텐츠를 작성하면 Hugo가 이를 HTML 파일로 변환해주는 방식으로 동작합니다. 데이터베이스나 서버 사이드 처리가 필요 없기 때문에 호스팅 비용이 거의 들지 않으며, 보안 취약점도 거의 없습니다.

PaperMod는 Hugo 커뮤니티에서 가장 많이 사용되는 테마 중 하나로, 심플하고 세련된 디자인과 빠른 로딩 속도, 다크 모드 지원, SEO 최적화 등 블로그에 필요한 기능들을 기본으로 제공합니다.

Hugo 설치

Hugo를 설치하는 방법은 운영체제마다 다릅니다. 아래에 주요 운영체제별 설치 방법을 안내합니다.

macOS

macOS에서는 Homebrew를 사용하면 가장 간편하게 설치할 수 있습니다. 터미널을 열고 아래 명령어를 실행하세요.

# brew 버전 확인
brew --version
 
brew install hugo
hugo version

Windows

Windows에서는 Chocolatey나 Scoop 패키지 매니저를 사용합니다. 아래 명령어 중 하나를 PowerShell에서 실행합니다.

# Chocolatey 사용 시
choco install hugo-extended
 
# Scoop 사용 시
scoop install hugo-extended

Linux

Ubuntu나 Debian 계열 리눅스에서는 snap을 사용하거나 직접 바이너리를 다운로드할 수 있습니다.

sudo snap install hugo

설치가 완료되면 아래 명령어로 버전을 확인해 정상적으로 설치됐는지 확인합니다.

hugo version

hugo v0.x.x 형태의 버전 정보가 출력되면 설치가 성공한 것입니다. Hugo는 Extended 버전을 설치하는 것을 권장합니다. Extended 버전은 SCSS/Sass 처리를 지원하며, PaperMod 테마도 이 버전을 요구합니다.

새 Hugo 사이트 만들기

Hugo 설치가 완료되었다면 이제 새 프로젝트를 생성합니다. 원하는 디렉토리로 이동한 뒤 아래 명령어를 실행합니다.

hugo new site my-blog
cd my-blog

my-blog 자리에는 원하는 프로젝트 이름을 넣으면 됩니다. 명령어를 실행하면 아래와 같은 구조의 디렉토리가 생성됩니다.

my-blog/
├── archetypes/
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── hugo.toml

설치된 버전에 따라 디렉토리 구조는 약간씩 다를수는 있지만 대략 위의 구조와 비슷할 것입니다.

각 디렉토리의 역할은 다음과 같습니다.

content: 블로그 글을 Markdown 파일로 작성하는 곳입니다.
static: 이미지, CSS, JavaScript, 폰트 등 정적 파일을 넣는 곳입니다.
layouts: 테마의 레이아웃을 커스터마이징할 때 사용합니다.
assets: SCSS, JS 등 빌드가 필요한 파일을 넣는 곳입니다.
themes: 설치한 테마가 들어가는 곳입니다.
hugo.toml: 사이트 전체 설정 파일입니다.

Git 초기화 및 PaperMod 테마 설치

Hugo 사이트 디렉토리에서 Git을 초기화하고 PaperMod 테마를 Git Submodule로 추가합니다. Submodule 방식을 사용하면 테마 업데이트를 쉽게 관리할 수 있습니다.

git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

명령어 실행이 완료되면 themes/PaperMod 디렉토리에 테마 파일이 다운로드됩니다.

hugo.toml 기본 설정

hugo.toml 파일을 열어 사이트 기본 설정을 입력합니다. 아래는 PaperMod 테마에 최적화된 기본 설정 예시입니다.

baseURL = "https://yourdomain.com/"
locale = 'ko-kr'
title = "내 블로그"
theme = "PaperMod"
paginate = 10
title = 'My New Hugo Project'
 
[params]
  env = "production"
  description = "블로그 설명을 입력하세요"
  keywords = ["블로그", "기술", "일상"]
  author = "작성자 이름"
  defaultTheme = "auto"
  disableThemeToggle = false
  ShowReadingTime = true
  ShowShareButtons = true
  ShowPostNavLinks = true
  ShowBreadCrumbs = true
  ShowCodeCopyButtons = true
  ShowWordCount = true
  ShowRssButtonInSectionTermList = true
  UseHugoToc = true
  ShowToc = true
  TocOpen = true
  
[params.homeInfoParams]
  Title = "안녕하세요! 👋"
  Content = "블로그에 오신 것을 환영합니다"
 
[[params.socialIcons]]
  name = "github"
  url = "https://github.com/yourusername"
 
[[params.socialIcons]]
  name = "twitter"
  url = "https://twitter.com/yourusername"
 
[pagination]
  pagerSize = 10
 
[menu]
  [[menu.main]]
    identifier = "posts"
    name = "글 목록"
    url = "/posts/"
    weight = 10
  [[menu.main]]
    identifier = "tags"
    name = "태그"
    url = "/tags/"
    weight = 20
  [[menu.main]]
    identifier = "search"
    name = "검색"
    url = "/search/"
    weight = 30
 
[outputs]
  home = ["HTML", "RSS", "JSON"]

baseURL은 나중에 실제 도메인을 연결하면 해당 주소로 변경해야 합니다. 현재는 임시로 유지하거나 Cloudflare Pages에서 제공하는 기본 URL로 설정해도 됩니다.

title에는 블로그에 대한 설명을 작성하시면 됩니다.

검색 기능 활성화

PaperMod의 검색 기능을 사용하려면 content/search.md 파일을 아래 내용으로 생성해야 합니다.

---
title: "검색"
layout: "search"
summary: "검색"
placeholder: "검색어를 입력하세요..."
---

첫 번째 글 작성

이제 블로그 글을 작성해 보겠습니다. Hugo에서 새 글을 생성할 때는 hugo new 명령어를 사용합니다.

hugo new posts/첫-번째-글.md

생성된 파일(content/posts/첫-번째-글.md)을 열면 아래와 같은 Front Matter가 자동으로 입력되어 있습니다.

---
title: "첫 번째 글"
date: 2026-04-20T00:00:00+09:00
draft: true
---

draft: true는 초안 상태를 의미하며, 이 상태에서는 배포 시 글이 공개되지 않습니다. 글 작성이 완료되면 draft: false로 변경하거나 해당 줄을 삭제해야 합니다.

Front Matter 아래부터 Markdown 형식으로 글 내용을 작성합니다.

---
title: "첫 번째 글"
date: 2026-04-20T00:00:00+09:00
draft: false
tags: ["Hugo", "블로그"]
description: "첫 번째 글입니다."
---
 
안녕하세요. 첫 번째 글입니다.

로컬에서 미리보기

글 작성 후 실제로 어떻게 보이는지 로컬에서 확인할 수 있습니다. 아래 명령어를 실행합니다.

hugo server -D

-D 플래그는 draft 상태의 글도 미리보기에 포함시키는 옵션입니다. 명령어를 실행하면 http://localhost:1313 주소로 브라우저에서 사이트를 확인할 수 있습니다. 파일을 수정하면 브라우저가 자동으로 새로고침 되므로 실시간으로 변경 사항을 확인할 수 있습니다.

GitHub 레포지터리 생성 및 연결

로컬에서 사이트가 정상적으로 작동하는 것을 확인했다면 이제 GitHub에 코드를 올릴 차례입니다.

GitHub 레포지터리 생성

GitHub에 로그인한 뒤 Repositories 메뉴로 이동합니다.
오른쪽 상단의 New 버튼을 클릭하고 Create a new repository 화면으로 이동합니다.
Repository name에 원하는 이름을 입력합니다. 예: my-blog
Public 또는 Private 중 원하는 공개 여부를 선택합니다. Cloudflare Pages에서 무료로 배포하려면 Public이어야 할 필요는 없으며 Private도 가능합니다.
README, .gitignore, license 추가 체크를 모두 해제한 뒤 Create repository를 클릭합니다.

레포지터리 생성하기 깃허브 계정에 로그인해서 간단하게 Repository를 만들어 줍니다

로컬과 GitHub 연결

생성된 레포지터리의 URL을 복사한 뒤, 터미널에서 아래 명령어를 순서대로 실행합니다.

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/my-blog.git
git push -u origin main

yourusername과 my-blog 부분은 본인의 GitHub 사용자 이름과 좀전에 만들었던 레포지터리 이름으로 변경하면 됩니다.

.gitignore 설정

Hugo 프로젝트에서 GitHub에 올릴 필요가 없는 파일들을 제외하기 위해 .gitignore 파일을 프로젝트 루트에 생성합니다.

public/
resources/_gen/
.hugo_build.lock
node_modules/

public/ 디렉토리는 Hugo가 빌드할 때 자동으로 생성되는 파일들이 들어가는 곳으로, Cloudflare Pages에서 자체적으로 빌드하기 때문에 GitHub에 올릴 필요가 없습니다.

Cloudflare Pages 배포

GitHub에 코드가 올라갔다면 이제 Cloudflare Pages를 사용해 무료로 배포할 수 있습니다. Cloudflare Pages는 GitHub 레포지터리와 연동하여 코드가 push될 때마다 자동으로 빌드하고 배포해 주는 서비스입니다.

Cloudflare 계정 및 Pages 설정

Cloudflare 홈페이지(cloudflare.com)에 접속하여 계정을 생성하거나 로그인합니다.
왼쪽 메뉴에서 Compute의 서브메뉴 중 Workers & Pages를 클릭합니다.
Create application 버튼을 클릭한 뒤 하단의 Looking to deploy Pages? Get started를 선택합니다.
계속해서 Import an existing Git repository 항목의 Get Started를 클릭합니다.

GitHub 연동

GitHub account에서 자신의 깃허브 계정을 선택합니다. 아직 로그인 전이라면 로그인 합니다.
앞에서 만들었던 레포지터리를 선택합니다.
Begin setup을 클릭합니다.

깃허브와 연동하기 깃허브에서 수정이 발생하면 자동으로 가져올 수 있도록 레포지터리를 연결합니다.

빌드 설정

레포지터리를 선택한 뒤 빌드 설정 화면이 나타납니다. 아래와 같이 설정합니다.

Project name: 원하는 프로젝트 이름 입력 (배포 URL에 사용됨)
Production branch: main
Framework preset: Hugo 선택
Build command: hugo --gc --minify
Build output directory: public

설정을 마친 뒤 Save and Deploy 버튼을 클릭합니다. 첫 빌드는 1~2분 정도 소요됩니다. 빌드가 완료되면 프로젝트명.pages.dev 형태의 URL로 블로그에 접속할 수 있습니다.

자동 배포 확인

이후 GitHub의 main 브랜치에 코드를 push할 때마다 Cloudflare Pages가 자동으로 빌드하고 배포합니다. 배포 상태는 Cloudflare Pages 대시보드에서 실시간으로 확인할 수 있습니다.

커스텀 도메인 연결

Cloudflare Pages에서 제공하는 기본 도메인(*.pages.dev) 대신 직접 구매한 도메인을 연결하면 훨씬 전문적인 블로그를 운영할 수 있습니다.

도메인 준비

도메인이 없다면 Cloudflare Registrar, Namecheap, GoDaddy 등 도메인 등록 업체에서 구매할 수 있습니다. Cloudflare에서 직접 도메인을 구매하면 추가 설정 없이 Pages와 바로 연동할 수 있어 편리합니다.

Cloudflare Pages에 도메인 연결

Cloudflare Pages 대시보드에서 본인의 프로젝트를 클릭합니다.
Custom domains 탭을 클릭합니다.
Set up a custom domain 버튼을 클릭합니다.
연결할 도메인 주소를 입력합니다. 예: myblog.com 또는 서브도메인 blog.myblog.com

도메인 DNS 설정

도메인이 Cloudflare에 등록된 경우와 외부 업체에 등록된 경우의 설정 방법이 다릅니다.

Cloudflare에 등록된 도메인인 경우:

Cloudflare가 자동으로 DNS 레코드를 추가해줍니다. 별도 설정 없이 확인 버튼만 클릭하면 됩니다.

외부 업체에 등록된 도메인인 경우:

도메인 등록 업체의 DNS 관리 페이지에서 아래 레코드를 추가합니다.

루트 도메인 사용 시 (예: myblog.com):
- Type: CNAME
- Name: @ 또는 도메인 이름
- Value: 프로젝트명.pages.dev
서브도메인 사용 시 (예: blog.myblog.com):
- Type: CNAME
- Name: blog
- Value: 프로젝트명.pages.dev

일부 DNS 제공업체는 루트 도메인에 CNAME 레코드를 허용하지 않습니다. 이런 경우 Cloudflare로 네임서버를 이전하면 CNAME Flattening 기능을 통해 루트 도메인에도 CNAME을 사용할 수 있습니다.

Cloudflare로 네임서버 이전 (권장)

외부에서 구매한 도메인이더라도 Cloudflare로 네임서버를 이전하면 CDN, DDoS 보호, 무료 SSL 인증서 등 다양한 Cloudflare의 기능을 활용할 수 있습니다.

Cloudflare 대시보드 왼쪽 메뉴에서 Websites를 클릭합니다.
Add a site를 클릭하고 도메인 주소를 입력합니다.
무료 플랜을 선택합니다.
Cloudflare가 기존 DNS 레코드를 자동으로 감지하여 표시합니다. 확인 후 Continue를 클릭합니다.
Cloudflare에서 제공하는 네임서버 주소 두 개를 복사합니다. 예: aria.ns.cloudflare.com, bob.ns.cloudflare.com
도메인 등록 업체 관리 페이지에서 네임서버를 Cloudflare에서 제공한 주소로 변경합니다.
네임서버 변경은 전파되는 데 최대 48시간이 소요될 수 있습니다.

네임서버 이전이 완료되면 Cloudflare Pages의 Custom domains 설정에서 도메인을 추가할 때 자동으로 DNS 설정이 완료됩니다.

SSL 인증서 적용 확인

Cloudflare Pages는 커스텀 도메인에 자동으로 무료 SSL 인증서를 발급합니다. 도메인 연결이 완료된 뒤 https:// 로 접속되는지 확인합니다. SSL 인증서 발급에는 수 분에서 최대 24시간이 소요될 수 있습니다.

hugo.toml의 baseURL 업데이트

도메인 연결이 완료되면 hugo.toml의 baseURL을 실제 도메인 주소로 업데이트합니다.

baseURL = "https://myblog.com/"

변경 후 GitHub에 push하면 Cloudflare Pages가 자동으로 재빌드 및 재배포합니다.

PaperMod 주요 기능 활용

PaperMod 테마는 다양한 기능을 제공합니다. 자주 사용되는 주요 기능들을 소개합니다.

다크 모드

hugo.toml의 params 섹션에서 defaultTheme = "auto"로 설정하면 사용자의 운영체제 설정에 따라 자동으로 다크/라이트 모드가 적용됩니다. dark 또는 light로 고정할 수도 있습니다.

Table of Contents (목차)

긴 글에는 목차를 자동으로 생성할 수 있습니다. hugo.toml에서 UseHugoToc = true로 설정하거나, 개별 글의 Front Matter에서 ShowToc: true를 추가합니다.

커버 이미지

글에 커버 이미지를 추가하려면 Front Matter에 아래 내용을 추가합니다.

---
cover:
  image: "이미지파일명.jpg"
  alt: "이미지 설명"
  caption: "이미지 캡션"
  relative: true
---

이미지 파일은 글 파일과 같은 디렉토리에 놓거나 static/images/ 폴더에 저장합니다.

프로필 모드

홈 화면을 프로필 형태로 변경하려면 hugo.toml에서 아래 설정을 추가합니다.

[params]
  profileMode.enabled = true
  profileMode.title = "이름"
  profileMode.subtitle = "소개 문구"
  profileMode.imageUrl = "프로필이미지.jpg"
  profileMode.imageWidth = 120
  profileMode.imageHeight = 120

글 업데이트 워크플로

블로그를 운영하면서 새 글을 발행하는 기본적인 워크플로는 다음과 같습니다.

hugo new posts/글제목.md 명령어로 새 파일을 생성합니다.
에디터로 파일을 열어 Front Matter를 수정하고 본문을 작성합니다.
hugo server -D로 로컬에서 미리보기를 확인합니다.
완성된 글은 draft: false로 변경합니다.
git add . → git commit -m "새 글 추가" → git push 명령어로 GitHub에 올립니다.
Cloudflare Pages가 자동으로 빌드하고 배포합니다.

마치며

Hugo와 PaperMod, 그리고 Cloudflare Pages의 조합은 현재 개인 블로그 운영에 있어 가장 이상적인 선택 중 하나입니다. Hugo의 빠른 빌드 속도, PaperMod의 세련된 디자인, Cloudflare Pages의 무료 호스팅과 CDN, 그리고 자동 배포까지 모두 무료로 이용할 수 있습니다. 한 번 설정해두면 이후에는 Markdown 파일 작성과 git push만으로 블로그를 운영할 수 있어 콘텐츠 작성에만 집중할 수 있습니다.

처음에는 설정할 것이 많아 복잡하게 느껴질 수 있지만, 이 가이드를 따라 한 단계씩 진행하면 1~2시간 안에 나만의 블로그를 완성할 수 있을 것입니다. 한 번 완성된 블로그는 유지 관리가 매우 간편하기 때문에 어렵더라도 끝까지 완수하시기 바랍니다.

하마창고

블로그

PaperMod 테마 + GitHub + CloudFlare 적용 완벽 가이드