Featured Image for [hugo] hugo + github 로 개인 블로그 구축하기
2025.05.09
[hugo] hugo + github 로 개인 블로그 구축하기
📚 /hugo 튜토리얼

1. 소개

Hugo + GitHub hosting + Github Action 조합으로 30 분 만에 개인 개발 블로그를 구축하기

이런 저런 이유로 인터넷 공간 한 구석에 나만을 위한 원룸이 필요할 때가 있다. 개인 메모용, 혹은 지식을 공유하기 위한 개발 블로그 등등… 이를 위한 플랫폼으로 네이버 블로그, 티스토리, Medium 등 종류가 참 다양하지만, 나는 마크다운(.md) 기반으로 필기하는 습관이 있어 Hugo + GitHub Pages 조합을 선택하였다. 이 방식은 다음과 같은 이점을 제공한다.

1️⃣ 마크다운 그대로 작성할 수 있다!
2️⃣ 정적 사이트이므로 속도가 빠르고 보안 부담이 적다.
3️⃣ GitHub Pages를 이용해 무료로 호스팅할 수 있다.

Hugo 테마 사이트에 들어가면 전세계 Hugo 유저들이 제작한 블로그 테마가 등록되어 있다. 다른 테마를 원하는 경우 아래 링크에서 더 많은, 더 예쁜 테마를 확인해보자! 각 테마 내부에 데모 사이트 접속부터 실제 설치-사용방법까지 적혀있기 때문에 초보자라도 쉽게 따라할 수 있다. 물론 대부분 영어로 적혀 있기 때문에 시행착오가 존재할 수 있고, 업데이트가 종료된 테마인 경우 최신 Hugo 엔진에서 작동하지 않는 경우도 있다. 따라서 같은 고민을 겪을 초보자를 위해 이 가이드를 작성하며, 우선 내가 작성한 freshPink 테마를 사용하고자 한다.



2. 기본 정보



3. Github Actions

소스코드와 결과물의 분리에서 오는 관리의 이득, 그리고 배포과정 자동화에서 오는 편리성과 휴먼에러 방지 목표로 Github Actions 을 사용하는 것이 좋다.



4. freshPink 테마 살펴보기

이번 가이드로 사용해볼 테마는 freshPink 테마이다. 다음 링크를 접속해서 어떻게 생긴 테마인지, 데모사이트는 어떤지 한번 살펴보자. 마음에 들지 않는다면, 일단 한번 배포까지 연습해보고 나중에 다른 테마로 갈아끼우면 그만이다. 혹은 fork를 떠서 마개조해도 좋다.



5. 설치 방법


5-1. 로컬에 블로그 설치하기

5-1-1. Go , Hugo 설치하기

# Go, Hugo 설치하기
brew install go
brew install hugo

# extended 버전인지 확인하기
hugo version

hombrew 를 통해 Hugo 를 설치할 수 있다. 아직 homebrew가 없다면 아래 링크에서 설치하자. 또한, Hugo가 extended 버전으로 설치되었는지 잘 확인하자!


5-1-2. Github repository 만들고 Hugo 세팅하기

# 클론 받기
git clone https://github.com/<username>/<username>.github.io.git

# 해당 디렉토리로 이동
cd <username>.github.io

# Hugo site 생성하기 (강제)
hugo new site . --force

우선 username.github.io 이름으로 Public 레포를 만들고, 클론 받자. 그리고 해당 디렉토리로 이동해서 그 디렉토리 내부에 Hugo 사이트를 생성하자!


5-1-3. .gitignore 추가

/public/

.gitignore 파일을 만들고 안에 /public/ 을 추가하자. 어처피 우리가 나중에 호스팅할 파일은 다른 브랜치에 모여있을 예정이기 때문이다.


5-1-4. hugo.toml 설정하기

디렉토리에 생성된 hugo.toml 파일을 열고, 기존 내용은 모두 지운 뒤 아래 내용을 복사해서 붙여넣자! 그리고 각 부분은 본인 정보에 맞게 채워넣어 보자.

baseURL = 'https://example.org/' # your git repository address
title = 'freshpink' # your own blog title
languageCode = 'en-us'
canonifyURLs = true

[[menus.main]]
name = 'Home'
pageRef = '/'
weight = 10

[[menus.main]]
name = 'TAGS'
pageRef = '/tags/'
weight = 20

[[menus.main]]
name = 'ABOUT'
pageRef = '/about/'
weight = 30

[module]
  [module.hugoVersion]
    extended = true
    min = "0.116.0"
  [[module.imports]]
    path = "github.com/elecbrandy/freshpink"

[params]
  # --- Site Metadata ---
  googleAnalytics = "G-000000000"
  copyright = 'Copyright © 2024 elecbrandy'

  # --- Theme & Display Settings ---
  primaryColor = "#fa8b84"
  math = true

  # --- GitHub Chart ---
  githubUsername = "elecbrandy"
  showGithubChart = true

  # --- Main Image ---
  mainImageUrl = "https://zrr.kr/0wve8W"
  showMainImage = true

[taxonomies]
  tag = 'tags'

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

⤵️ 변경 가능한 부분들


5-1-5. theme 받아오기

설정을 마쳤다면 아래 명령어를 입력해 theme 파일을 받아오자.

# go.mod 만들기 -> 모듈로 테마를 관리하겠다는 뜻 -> go.mod 가 생성됨
hugo mod init github.com/username/username.github.io

# hugo.toml 파일에 지정한 테마를 모듈로 다운받는다는 뜻
hugo mod get

# 다운로드 후 모듈 정리 등
hugo mod tidy

5-1-6. 로컬에서 확인하기

# 새로운 글 만들어보기
hugo new posts/hello.md

# 로컬 서버 띄우기 (캐시 무시)
hugo server --ignoreCache --noHTTPCache

# 확인했다면 일단 푸시해주자
git add .
git commit -m "blog init"
git push origin main

우선 테스트용 게시글을 하나 만들어본 후, 로컬 서버를 실행해 블로그가 잘 작동하는지 확인해보자. 인터넷 브라우저를 켜고 http://localhost:1313 주소로 접속하면 적용된 테마를 볼 수 있다!


5-1-7. 업데이트

hugo mod get -u
hugo mod tidy

만약 사용하던 테마에 새로운 기능이 추가되었다면 -> 테마를 최신 버전으로 업데이트하기 위해 위 명령어를 사용하면 된다.



5-2. Github Action 설정하기

5-2-1. workflow 파일 작성

프로젝트 루트에 .github/workflows/ 디렉토리를 만들고 그 안에 deploy.yml 을 생성한다. deploy.yml 에 아래 내용을 붙여넣는다.

name: Deploy Hugo Site

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          submodules: true

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

      - name: Build site
        run: hugo --destination public

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          keep_files: false
  1. Push main 브랜치에 푸시되면 워크플로가 실행된다.
  2. Build Hugo가 public/ 폴더에 정적 사이트를 생성한다.
  3. Deploy public/ 내용이 gh-pages 브랜치로 푸시된다.
  4. Serve GitHub Pages가 gh-pages 브랜치를 호스팅한다.

5-2-2. 토큰 권한 부여


5-2-3. Github Pages 위치 지정

이제 Github Page가 어느 브랜치의 어떤 폴더를 웹사이트로 쓸지 알려줘야 한다!



6. How to use?

이제 블로그 디렉토리에서 한창 글을 쓰다가, 단순 git push 만으로 블로그가 자동 빌드‧배포된다. 본격적인 테마의 사용 방법이나, 커스텀 방법이 궁금하다면 아래 링크를 읽어보자.



📚 /hugo 튜토리얼