Etc

Github.io 블로그에 Hugo 테마 세팅하기

Hugo 블로그 테마 세팅하기

서론

취업한 기념으로..
기술 블로그를 제대로 세팅해보려고 다양한 포맷을 찾아보았습니다.

velog, tistory 보다는 커스텀이 가능한 oopy(notion 기반), github.io로 추려졌고,
아무래도 oopy는 지속적인 비용이 발생하기에..
기존에 있던 github.io 블로그에 새로운 테마를 적용하기로 결정했습니다!

다양한 블로그 테마를 찾아보다가 Hugo에서 원하는 테마를 발견했습니다.
hugo-theme-stack

hugo-example-site
이 테마를 적용하기로 결정!

하지만 세팅을 완료하면서 굉장히 많은 시행착오를 겪었기에..
다른분들은 좀 더 쉽게 하시길 바라며 Hugo 블로그 세팅법을 포스팅 해봅니다!

참고 사항

  • 운영체제 : Windows 10, 11
  • 기본 준비사항 : Git 설치, Github 가입
  • Github.io 블로그에 Hugo 테마를 적용하는 상황에 맞춰진 게시글입니다.
  • 더 자세한 내용이 필요하시면 공식 문서를 참고해주세요.
  • 다음 포스팅에서는 Github.io Repository를 submodule로 두지 않고 Github Actions를 이용하여 배포하는 방법을 알려드립니다.

Hugo 설치하기

먼저 Hugo를 설치해야합니다.
그리고 Hugo extended 버전에서는 SCSS/SASS를 지원합니다.
대부분 SCSS를 사용하기 때문에 꼭 extended 버전을 설치해주셔야 합니다!

Hugo Installation
이곳에서 각각의 운영체제에 맞게 설치하시면 되고,
저는 Windows 환경에서 설치하는 방법을 보여드릴게요!


Package Manager 설치

Hugo를 Windows 환경에 설치하기 위해서는 패키지 매니저가 필요합니다.
먼저 chocolatey라는 윈도우 환경 패키지 매니저를 다운받습니다.

PowerShell을 관리자 권한으로 실행
powershell
→ 윈도우 키를 누르고 powershell을 입력하시면 됩니다.
→ 관리자 권한으로 실행!

PowerShell에 아래 명령어를 입력하면 chocolatey가 설치됩니다.

1

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

install-chocolatey

설치가 완료되었는지 확인하려면 PowerShell에 choco라는 명령어를 입력해보세요!
chocolatey 버전 정보가 나온다면 설치가 완료된 상태입니다.

choco-version

Hugo 설치

이제 Hugo를 설치할 수 있습니다!

PowerShell에 아래 명령어를 입력하면 Hugo가 설치됩니다. (extended 버전)

1

choco install hugo-extended -confirm

install-hugo

설치가 완료되었는지 확인하려면 PowerShell에 hugo version이라는 명령어를 입력해보세요!
hugo 버전 정보가 나온다면 설치가 완료된 상태입니다.

hugo-version

블로그 세팅하기

먼저 hugo 블로그 테마의 특징을 말씀드리자면
hugo의 폴더 구조에 맞춰서 markdown 양식의 게시글을 작성하고,
hugo 명령어를 통해 html 파일로 변환해서 웹 사이트로 보여지게 됩니다.

따라서 저는 두 개의 git repository를 생성해서
하나의 repository에서는 hugo 블로그 테마의 파일들을 관리하고, 다른 하나의 repository(github.io)에서는 html 파일로 변환한 내용들만 관리하도록 세팅했습니다.


두 개의 git repository 세팅

Blog repository

먼저 hugo 블로그 테마의 파일들을 관리할 repository를 생성합니다.
repository 이름은 마음대로 설정해주시면 됩니다. 저는 blog로 설정했어요!
그리고 편의상 앞으로 이 repository를 blog repository라고 부르겠습니다.
이 repository는 private repo로 설정하셔도 됩니다.

Github.io repository

그리고 github.io 블로그 repository를 생성합니다.
이 repository는 이름을 꼭 {Github_닉네임}.github.io로 설정하셔야 해요!
그래야 github page가 생성됩니다.
제 github 닉네임은 cse0518이므로 repository 이름을 cse0518.github.io로 설정했습니다.
이 repository는 꼭 public repo로 설정하셔야 됩니다.


hugo 블로그 생성

이제는 기본적인 Hugo 블로그 틀을 생성합니다.
블로그 폴더를 생성할 위치에서 hugo new site {폴더명} 명령어를 입력합니다.

1

hugo new site {폴더명}

new-site

저는 Documents 위치에서 blog라는 폴더명으로 블로그 틀을 만들었습니다.
그리고 아까 만들어놓은 blog repository를 새로 만든 폴더(blog)에 연동하겠습니다.

cd blog 명령어로 blog 폴더로 이동
→ git init 명령어로 git 저장소 생성
→ git remote add origin {repository_URL} 명령어로 원격 저장소를 연동합니다.
아까 생성한 blog repository의 URL 주소를 넣으시면 됩니다!

git-remote
혹시 안된다면 clone 해오셔도 됩니다.

그럼 repository 연동이 완료되었고, 이제 테마를 적용해보겠습니다!


hugo 테마 세팅

블로그 폴더에 themes 라는 폴더가 있습니다.
이 폴더안에 테마를 받아서 연결하는 작업을 해보겠습니다.

저는 hugo-theme-stack이라는 테마를 기준으로 설명하겠습니다! theme-link

먼저 테마 깃허브 링크를 복사해주시고,
git submodule add -b master {복사한_URL} themes/{테마_이름} 명령어를 입력합니다.

1

git submodule add -b master {테마_Github_URL} themes/{테마_이름}

theme-submodule

해당 테마가 themes/{테마_이름} 위치에 서브 모듈로 추가됩니다.
이제 이 테마를 설정 파일(config.toml)에 등록해줍니다.

1

theme = '{테마_이름}'

toml

그리고 hugo server 명령어를 입력해 실행해보면 블로그 서버가 실행됩니다.
localhost:1313으로 접속하라고 나오네요.
종료할때는 Ctrl + C를 누르시면 됩니다.

hugo-server

테마가 적용된 것을 확인할 수 있습니다! empty-site 이제 설정을 커스터마이징하고, 포스트를 작성하시면 됩니다.

일단 themes/{테마_이름} 폴더에 있는 exampleSite를 적용하시고 감 잡으시는 것을 추천드립니다!

exampleSite의 content 폴더 내부 파일들을
blog 폴더의 content 폴더로 그대로 복사하시고,
exampleSite의 설정 파일(config.yaml)을 blog 폴더로 복사하시면 됩니다.
그리고 blog 폴더의 toml 파일은 삭제하면 yaml 파일로 적용이 됩니다.

example-site
적용된 모습!

config 파일 커스터마이징

config 파일을 수정하시면서 커스터마이징을 하면 되는데,
중요한 부분만 가볍게 설명해볼게요!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

DefaultContentLanguage: en # ko로 설정하면 한국어로 보여집니다.
timeZone: Asia/Seoul # 한국 타임존 설정
paginate: 5 # 한 페이지에 게시글이 몇 개씩 보여지는지 설정
title: 최승은 (Choi SeungEun) # 좌측 타이틀 설정

# params 하위 설정
params:
  favicon: /favicon.ico # static/img/favicon.ico 위치에 파비콘 이미지 저장
  footer: # 블로그 최하단부에 몇년도부터 블로그를 운영했는지와 커스텀 텍스트 설정
    since: 2021
    customText: Choi SeungEun Tech Blog
  sidebar:
    emoji: 😎 # 좌측 개인 사진 옆 이모지 설정
    subtitle: Back-end Engineer # 타이틀 하단 부제 설정
    avatar: # 좌측 개인 사진 설정
      src: img/avatar.png # assets/img/avatar.png 위치에 개인 사진 저장
  comments: # 댓글 설정
    enabled: true
    provider: utterances # 원하는 댓글 앱 지정
    utterances: # 저는 utterances 댓글 앱으로 설정했습니다
      repo: "cse0518/cse0518.github.io" # 댓글이 달리면 이슈가 생성될 repository
      issueTerm: pathname # 이슈 제목
  widgets:
    homepage: # 블로그 홈 화면 우측에 위젯 설정
      - type: search
      - type: archives
        params:
          limit: 3 # 최대 몇 개의 년도를 보여줄지 설정
      - type: categories
        params:
          limit: 10 # 최대 몇 개의 카테고리를 보여줄지 설정
      - type: tag-cloud
        params:
          limit: 10 # 최대 몇 개의 태그를 보여줄지 설정

# menu 하위 설정
menu:
  social: # 좌측 타이틀 하단에 소셜 링크 설정(깃허브 등)
    - identifier: mail # 별칭
      name: Mail # 실제 표시될 이름
      url: mailto:csedev0518@gmail.com # 연결될 주소(URL)
      weight: 1 # 몇 번째 순서로 표시될지 설정
      params:
        icon: mail # assets/icons/mail.svg 위치에 아이콘 저장

    - identifier: github
      name: GitHub
      url: https://github.com/cse0518
      weight: 3
      params:
        icon: brand-github

# markup 하위 설정
markup:
  goldmark:
    renderer:
      unsafe: true # true로 설정 시 html 태그 활용 가능

파비콘 설정
static/img/favicon.ico 위치에 파비콘 이미지를 저장하고,
config 설정에서 params: favicon: /favicon.ico을 등록해주면
아래 사진에 최승은 Tech Blog 좌측 파비콘 설정이 가능합니다!

favicon

좌측 메뉴 설정

left-bar

avatar → params: sidebar: avatar: src: {아바타_저장위치} 설정
emoji → params: sidebar: emoji: {이모지} 설정
title → title: {타이틀} 설정
subtitle → params: sidebar: subtitle: {서브_타이틀} 설정
social menu → menu: social: {소셜_메뉴} 설정

main menu → content/page 위치에 설정
저는 content/_index.md 파일에 Home 메뉴를 설정했고,
content/page/ 위치에 about, archives, search 메뉴를 설정했습니다.

1
2
3
4
5
6
7
8
9

<!-- Home 메뉴 md 파일 예시 -->
---
menu:
  main:
    name: Home
    weight: 2
    params:
      icon: home
---

댓글 설정(utterances)

게시글에 댓글을 달 수 있게 설정이 가능합니다.
저는 utterances 댓글 앱으로 설정했습니다.
utterances 댓글은 깃허브 로그인으로 간편하게 댓글을 작성할 수 있고,
무료로 광고 없이 빠르게 이용 가능합니다.
그리고 댓글이 달리면 github issue로 확인도 가능합니다!

https://github.com/apps/utterances에서 설치가 가능합니다.

repo-access

먼저 어떤 repository에 알림이 가도록 할지 선택합니다.
저는 github.io repository에만 issue 알림이 오도록 연동했습니다.
Install 버튼을 누르시면 됩니다!

다음 페이지에서 repository 이름을 작성해주시고(ex. cse0518/cse0518.github.io),
issue가 어떤 제목으로 생성될 지 설정합니다.
pathname이나 URL로 설정하는게 빠르게 확인하기에 좋을 것 같습니다!

issue-mapping

다음 나오는 Theme를 확인하시고, config 파일에 적용하시면 됩니다.

1
2
3
4
5
6
7
8

# params 하위 설정
params:
  comments: # 댓글 설정
    enabled: true
    provider: utterances # utterances 댓글 활성화
    utterances:
      repo: "cse0518/cse0518.github.io" # 댓글이 달리면 issue가 생성될 repository
      issueTerm: pathname # issue 제목

다음과 같이 댓글 앱이 활성화됩니다!

utterances

다음 포스팅 예고

이제 블로그를 Github.io에 배포하는 일만 남았습니다.
배포하는 방법은 다양합니다.
수작업으로 하나하나..
또는 스크립트를 작성해놓고 실행..
또는 Github Actions를 활용해서 배포 자동화!

다음 포스팅에서 Github Actions를 활용한 배포 자동화를 알려드리겠습니다.

© 2021 - 2023 최승은 (Choi SeungEun)
Choi SeungEun Tech Blog
Built with Hugo
Theme Stack designed by Jimmy