Windows에서 Hugo와 Github Pages로 블로그 만들기(+커스텀 도메인 연결)

_Big 2025. 5. 17.

안녕하세요. 윈도우 환경에서 Github Pages와 Hugo 정적 사이트 생성기를 이용해서 블로그를 만들고, 사용자 도메인을 연결하는 방법을 단계별로 정리했습니다. Jekyll로 만들었던 블로그가 구글 서치 콘솔에서 색인 생성에 문제가 있는 것 같아 이번에 Hugo를 테스트 하면서 관련 내용을 정리한 것입니다. 각 단계마다 필요한 명령어 예시를 함께 작성해서 따라하기 쉬우실 것입니다.

1. Hugo에 대해서 간단히 알아봅시다.

Hugo는 아주 빠르고 유연한 정적 사이트 생성기입니다. 마치 레고 블록처럼 미리 만들어진 템플릿과 콘텐츠 파일을 합쳐서 웹사이트를 만들어주는 도구라고 생각하시면 좋습니다. 복잡한 데이터베이스나 서버 측 코딩 없이도 멋진 웹사이트를 만들 수 있다는 점이 매력적이죠.

주요 특징을 좀 더 자세히 살펴볼까요?

엄청난 속도: Hugo는 Go 언어로 만들어져서 웹사이트를 빌드하는 속도가 매우 빠릅니다. 콘텐츠가 많아도 순식간에 결과물을 만들어내죠.
쉬운 사용법: HTML, CSS, Markdown 같은 웹 표준에 익숙하다면 Hugo를 쉽게 배우고 사용할 수 있습니다.
다양한 테마: Hugo Themes 웹사이트에서 수많은 무료 및 유료 테마를 골라서 적용할 수 있습니다. 원하는 디자인을 쉽게 찾고 커스터마이징할 수 있죠.
강력한 템플릿 시스템: Go 템플릿 언어를 사용해서 웹사이트의 구조와 디자인을 자유롭게 정의하고 제어할 수 있습니다.
유연한 콘텐츠 관리: Markdown, YAML, TOML 등 다양한 형식으로 콘텐츠를 작성하고 관리할 수 있습니다.
내장 서버: 개발 및 테스트를 위한 빠른 내장 웹 서버를 제공합니다.
다국어 지원: 여러 언어로 된 웹사이트를 쉽게 구축하고 관리할 수 있도록 지원합니다.
활발한 커뮤니티: 전 세계적으로 많은 사용자와 개발자 커뮤니티가 활발하게 활동하고 있어, 궁금한 점이나 문제 해결에 도움을 받을 수 있습니다.

2. Hugo 설치(Wondows 기준)

최신 버전의 Hugo(Extended 버전)을 설치해야 합니다. Windows에서 Hugo를 설치하는 방법은 다음과 같습니다.

2.1 패키지 매니저 이용

Windows 10/11에서는 Chocolatey를 사용하면 편리합니다. 관리자 권한으로 PowerShell을 열고 아래 명령어를 실행하세요. (Extended 버전 설치) Chocolatey 설치 방법은 여기를 참고하세요.

choco install hugo-extended -y

위 명령을 실행하면 Hugo가 자동으로 다운로드 및 설치됩니다. 설치 후 명령 프롬프트나 PowerShell에서 hugo version을 입력해서 버전을 확인하세요. 성공적으로 설치되었다면 Hugo 버전 정보가 출력됩니다.

2.2 수동 설치

패키지 매니저를 사용하지 않을 경우, Hugo GitHub 릴리스 페이지에서 Windows용 Extended zip 파일을 직접 다운로드할 수도 있습니다. 압축을 풀어서 hugo.exe 파일을 원하는 경로(예: C:\Hugo\bin)에 두고, 해당 경로를 PATH 환경변수에 추가하면 됩니다. 이후 hugo version으로 정상 설치 확인이 가능합니다.

3. Github에서 새 프로젝트 저장소 만들기

블로그 파일을 저장할 Github 저장소를 생성할 단계입니다. Github에 로그인한 후 우측 상단의 '+' 버튼을 클릭하고 New repository를 선택합니다. 저장소 생성 페이지에서 아래와 같이 설정하세요.

Repository name: hugo-test (예시에서는 {user account}/hugo-test가 됩니다).
Public: 공개 저장소로 설정 (기본값).
Initialize this repository with: 체크하지 않아 빈 저장소로 만듭니다 (초기화 파일 없음).

설정을 마쳤으면 Create repository 버튼을 클릭하여 저장소를 만듭니다. 이제 GitHub에 빈 프로젝트 저장소가 생성되었습니다. 이 저장소에 Hugo로 생성한 사이트 파일들을 올릴 예정입니다.

4. Hugo 테마 선정

Hugo에는 수백 가지의 테마가 있으며, 그 중 심플하고 사용하기 쉬운 테마 몇 가지를 추천합니다. 테마는 사이트의 디자인과 기능을 결정하므로, 취향에 맞는 것으로 선택하면 됩니다. 더 많은 테마는 여기에서 참고하세요.

4.1 Cactus

개인 블로그에 적합한 깔끔하고 반응형인 테마입니다. 최소한의 디자인으로 콘텐츠에 집중할 수 있습니다.

4.2 PaperMod

빠르고 깨끗한 현대적인 디자인의 테마로, 다크 모드 지원 등 여러 유용한 기능을 제공합니다. 블로그에 많이 사용되는 인기 테마 중 하나입니다.

4.3 Ananke

Hugo 공식 튜토리얼에서 사용되는 기본 테마로, 기능이 갖춰진 심플한 블로그 테마입니다. 성능과 접근성 등의 모범 사례를 반영한 스타터 테마로 알려져 있습니다. 처음 Hugo를 사용할 때 입문용으로 좋습니다.

저는 Cactus가 마음에 들어서 이 테마로 진행했습니다. 참고하세요~

5. Hugo 사이트 초기화 및 테마 적용하기

이 단계에서는 Hugo로 새 사이트를 생성하고, 앞서 선택한 테마(Cactus)를 적용하겠습니다. Windows PowerShell 또는 Git Bash를 열어 진행하세요.

5.1 새 사이트 생성

원하는 작업 폴더로 이동한 뒤, hugo new site 명령을 실행합니다. 예를 들어 D:\Projects 폴더에서 다음을 수행합니다.

hugo new site hugo-test

위 명령을 실행하면 hugo-test 디렉토리에 Hugo 사이트 구조가 생성됩니다. 이제 이 폴더로 이동합니다.

cd hugo-test

5.2 Git 초기화

로컬 폴더를 Git 저장소로 만들고, 앞서 Github에서 만든 저장소와 연결합니다.

git init
git remote add origin https://github.com/{your account}/hugo-test.git

※ {your account} 부분을 자기 계정 정보로 변경하세요.

5.3 테마 추가 및 테마 활성화

선택한 테마(Cactus)를 themes 폴더에 추가합니다. Hugo 테마는 Github에 소스가 있으며 Git Submodule로 추가하는 방법을 권장합니다.

git submodule add https://github.com/monkeyWzr/hugo-theme-cactus.git themes/cactus

위 명령으로 themes/cactus 경로에 테마가 복제되고, .gitmodules 파일에 서브모듈 정보가 기록됩니다. (다른 테마를 쓰는 경우 해당 테마의 저장소 URL로 대체하세요.) 이제 기본 설정 파일 hugo.toml 을 열어 아래와 같이 테마 이름을 등록해야 사이트에 적용됩니다. vscode 등으로 파일을 오픈해서 작업하세요.

theme = "cactus"
baseURL = "https://{your account}.github.io/hugo-test/"

theme 항목에 테마 폴더명을 지정하고 baseURL을 Github Pages 주소로 설정합니다. 나중에 커스텀 도메인을 연결하면 baseURL을 해당 도메인으로 변경할 것입니다.

6. 테스트 블로그 글 작성 및 로컬 실행

Hugo 사이트에 글을 작성하는 방법은 매우 간단합니다. hugo new 명령을 사용하면 미리 정의된 폴더에 Markdown 형식의 글 파일이 생성됩니다. 아래 처럼 첫 블로그 글을 작성해봅시다. 프로젝트 루트 디렉토리에서 다음을 실행하세요.

hugo new posts/first-post.md

위 명령으로 content/posts/first-post.md 파일이 생성됩니다. Hugo는 이 파일 상단에 기본 메타데이터를 채워두는데, 예를 들면 다음과 같습니다.

+++
date = '2025-05-17T16:39:17+09:00'
draft = true
title = 'First Post'
+++

draft = true로 되어 있어 기본적으로 초안(draft) 상태로 생성됩니다. 이 메타데이터 아래 부분에 글 내용을 Markdown으로 작성하면 됩니다. Hugo가 Markdown을 HTML로 변환해 줍니다. 선호하는 편집기(VSCode 등)로 content/posts/first-post.md 파일을 열어 글을 추가 하세요. 이제 Hugo 내장 웹서버로 로컬에서 사이트를 미리보기할 수 있습니다. 프로젝트 폴더에서 아래 명령을 실행하세요.

hugo server -D

-D 옵션은 draft 글도 포함해서 보여주도록 하는 옵션입니다. 명령 실행 후 터미널에 표시되는 로컬 주소로 웹 브라우저를 열면 방금 작성한 글이 포함된 블로그 사이트를 활인할 수 있습니다. 테마가 제대로 적용됐는지, 글 내용과 레이아웃은 원하는 대로 나오는지 확인합니다. 다 되었으면 터미널에서 Ctrl +c로 로컬 서버를 종료합니다.

작성한 글을 공개하려면 content/posts/first-post.md 파일의 상단 draft = true를 false로 바꾸고 저장하세요. (초안을 그대로 두고 배포할 경우 해당 글은 실제 사이트에 포함되지 않습니다.)

hugo server -D 명령을 실행하면 cactus 테마를 사용하는 경우 에러가 발생됩니다. 그래서 아래와 같이 추가 작업이 필요합니다.

6.1 `resources.ToCSS` 오류 해결

themes\cactus\layouts\partials\head.html 이 파일을 열어서 아래 27 라인을 수정합니다.

변경전: {{- $styles := resources.Get "scss/style.scss" | resources.ExecuteAsTemplate "scss/style.scss" . | resources.ToCSS $options | resources.Fingerprint "sha512" }}
변경후: {{- $styles := resources.Get "scss/style.scss" | resources.ExecuteAsTemplate "scss/style.scss" . | css.Sass $options | resources.Fingerprint "sha512" }}

6.2 `GoogleAnalytics` 오류 해결

themes\cactus\layouts\partials\head.html 이 파일을 열어서 아래 46-50 라인을 삭제합니다.

  {{ if .Site.GoogleAnalytics }} <- 삭제
  {{ if .Site.Params.googleAnalyticsAsync }} <- 삭제
    {{ template "_internal/google_analytics_async.html" . }} <- 삭제
  {{ else }} <- 삭제
    {{ template "_internal/google_analytics.html" . }} <- 삭제
  {{ end }} <- 삭제
  {{ end }} <- 삭제

hugo.toml 파일을 열어서 다음 라인을 추가합니다.

googleAnalytics = ""

7. 사이트 생성 및 Github Pages에 배포

이제 작성된 Hugo 사이트를 정적 파일로 생성해서 Github Pages에 업로드할 차례입니다. Hugo는 hugo 명령으로 public/ 폴더에 정적 사이트를 생성합니다. 여기서는 Github Pages 특성상 docs/ 폴더를 사용하도록 출력 경로를 조정해서 생성하겠습니다.

7.1 정적 파일 생성

프로젝트 루트 디렉토리에서 다음 명령을 실행합니다.

hugo -d docs

이 명령은 public 대신 docs 폴더에 사이트용 정적 파일을 생성합니다. docs 폴더명을 사용하는 이유는 Github Pages 설정에서 docs 폴더를 사용할 것이기 때문입니다.

7.2 Github Pages 설정

Github 저장소(hugo-test)의 Settings > Pages 섹션으로 이동합니다. 그리고 아래와 같이 설정합니다.

Source: "Deploy from a branch" 선택 (그대로 두세요)
Branch: "master" 선택 (혹은 main)
Folder: "docs" 선택

이렇게 설정하면 master 브랜치의 docs/ 폴더를 Github Pages에서 사이트 소스로 인식하게 됩니다. 이제 설정을 저장하면 페이지 주소({your account}.github.io/hugo-test)가 활성화 됩니다.

7.3 변경사항 커밋 및 푸시

이제 로컬 저장소의 변경사항(테마 추가, 글 작성, 정적 파일 생성 등)을 모두 커밋하고 Github에 푸시합니다.

git add .
git commit -m "First Hugo site with theme and content"
git push -u origin master

themes/cactus의 변경 사항도 커밋 및 푸시하면 Github Pages에서 build 하는 과정에서 에러가 발생합니다.

7.4 배포 결과 확인

푸시 후 몇 십 초 내에 Github Pages가 사이트를 빌드합니다. 웹 브라우저에서 https://{your account}.github.io/hugo-test에 접속하여 방금 생성한 블로그가 정상적으로 보이는지 확인합니다.

8. 커스텀 도메인(hugotest.com) 연결 및 DNS 설정

Github Pages에서 제공하는 기본 주소 대신 hugotest.com 처럼 자신이 소유한 도메인을 사용할 수도 있습니다. 이를 위해 DNS 설정과 Github Pages 설정을 해야합니다.

8.1 DNS 레코드 추가

도메인 등록 업체의 관리 콘솔에서 DNS 설정을 아래와 같이 추가합니다. apex(하위 도메인이 없는 가장 기본적인 도메인, 즉 루트 도메인을 의미) 도메인(hugotest.com)에 대해 A 레코드를 Github Pages의 서버 IP 주소들로 설정합니다.

hugotest.com -> A -> 185.199.108.153
hugotest.com -> A -> 185.199.109.153
hugotest.com -> A -> 185.199.110.153
hugotest.com -> A -> 185.199.111.153
www.hugotest.com -> CNAME -> {your account}.github.io.

DNS 변경 사항이 반영되기 까지 보통 몇 분에서 몇 시간 소요될 수 있습니다. 조금 기다린 후 다음 작업을 진행합니다.

8.2 Github에 사용자 지정 도메인 추가

저장소 Settings > Pages 화면에서 Custom domain 항목을 사용할 도메인(hugotest.com)을 입력하고 Save를 클릭합니다. 이 작업을 하면 해당 저장소의 master 브랜치 docs/ 폴더에 자동으로 CNAME 파일이 생성되며, 내부에 연결한 도메인명이 기록됩니다. 그래서 로컬 저장소에서 git pull 명령을 실행 해 줘야합니다. (이건 다음 단계에서 실행합니다.) 이제 Enforce HTTPS 옵션을 활성화 합니다. 이 옵션을 켜두면 SSL 인증서가 자동으로 발급되어 https 로 안전하게 접속 가능합니다. (인증서 발급에는 최대 24시간 정도 걸릴 수 있다고 합니다. 참고하세요~)

8.3 기본 설정파일 수정

이제 기본 설정 파일 hugo.toml을 사용할 도메인 정보를 등록하고 적용할 차례입니다. 선호하는 편집기로 hugo.toml 파일을 열어서 아래와 같이 작업 합니다.

baseURL = 'https://hugotest.com/'

baseURL을 변경합니다. 그리고 커밋, 푸시를 실행합니다.

git pull (CNAME 파일이 저장소에 생성되었으니 먼저 내려 받습니다.)
git add .
git commit -m "baseURL 변경"
git push

8.4 최종 웹사이트 접속 확인

수고 하셨습니다. 작업이 끝났습니다. 웹 브라우저에서 https://hugotest.com 에 접속해서 사이트가 잘 뜨는지 확인합니다.

9. 향후 블로그 글 배포를 위한 기본 워크플로우

1. 콘텐츠 추가/수정: hugo new posts/새글.md 명령으로 초안 파일을 생성, content\posts\새글.md 파일을 열어서 편집
1. 로컬 테스트: hugo server -D로 로컬 미리보기를 실행해서 확인
1. draft 변경: 새글.md 파일의 draft 설정을 false로 변경
1. 사이트 재빌드: hugo -d docs 명령으로 정적 사이트를 다시 생성
1. Commit & Push: 모든 변경 사항을 커밋한 뒤 원격 저장소에 푸시
1. 확인

10. 끝

Windows 환경에서 Go 기반 Hugo 정정 사이트 생성기와 Github Pages를 활용해서 블로그를 만드는 방법에 대해 알아보았습니다. 물론 커스텀 도메인 설정하는 법도 설명했습니다. 여기서 사용한 Cactus 테마의 상세 설정 방법에 대해서는 다음 기회에 다시 정리해서 공유 하겠습니다. 그러면 블로그를 좀더 그럴듯하게 꾸미는 것이 가능해집니다.

저작자표시 비영리 변경금지 (새창열림)

Windows에서 Hugo와 Github Pages로 블로그 만들기(+커스텀 도메인 연결)

1. Hugo에 대해서 간단히 알아봅시다.

2. Hugo 설치(Wondows 기준)

2.1 패키지 매니저 이용

2.2 수동 설치

3. Github에서 새 프로젝트 저장소 만들기

4. Hugo 테마 선정

4.1 Cactus

4.2 PaperMod

4.3 Ananke

5. Hugo 사이트 초기화 및 테마 적용하기

5.1 새 사이트 생성

5.2 Git 초기화

5.3 테마 추가 및 테마 활성화

6. 테스트 블로그 글 작성 및 로컬 실행

6.1 `resources.ToCSS` 오류 해결

6.2 `GoogleAnalytics` 오류 해결

7. 사이트 생성 및 Github Pages에 배포

7.1 정적 파일 생성

7.2 Github Pages 설정

7.3 변경사항 커밋 및 푸시

7.4 배포 결과 확인

8. 커스텀 도메인(hugotest.com) 연결 및 DNS 설정

8.1 DNS 레코드 추가

8.2 Github에 사용자 지정 도메인 추가

8.3 기본 설정파일 수정

8.4 최종 웹사이트 접속 확인

9. 향후 블로그 글 배포를 위한 기본 워크플로우

10. 끝

댓글

티스토리툴바

Windows에서 Hugo와 Github Pages로 블로그 만들기(+커스텀 도메인 연결)

1. Hugo에 대해서 간단히 알아봅시다.

2. Hugo 설치(Wondows 기준)

2.1 패키지 매니저 이용

2.2 수동 설치

3. Github에서 새 프로젝트 저장소 만들기

4. Hugo 테마 선정

4.1 Cactus

4.2 PaperMod

4.3 Ananke

5. Hugo 사이트 초기화 및 테마 적용하기

5.1 새 사이트 생성

5.2 Git 초기화

5.3 테마 추가 및 테마 활성화

6. 테스트 블로그 글 작성 및 로컬 실행

6.1 resources.ToCSS 오류 해결

6.2 GoogleAnalytics 오류 해결

7. 사이트 생성 및 Github Pages에 배포

7.1 정적 파일 생성

7.2 Github Pages 설정

7.3 변경사항 커밋 및 푸시

7.4 배포 결과 확인

8. 커스텀 도메인(hugotest.com) 연결 및 DNS 설정

8.1 DNS 레코드 추가

8.2 Github에 사용자 지정 도메인 추가

8.3 기본 설정파일 수정

8.4 최종 웹사이트 접속 확인

9. 향후 블로그 글 배포를 위한 기본 워크플로우

10. 끝

댓글

티스토리툴바

6.1 `resources.ToCSS` 오류 해결

6.2 `GoogleAnalytics` 오류 해결