Hugo와 Github page로 블로그 구축

hugo를 선택한 이유

github page를 이용하여 블로그를 운영하는데 다양한 generator가 존재한다.

가장 유명한 generator로는 Ruby 기반의 Jekyll이 있다. Jekyll은 가장 github의 star 수가 많은 만큼 theme도 많고 한글 reference도 많다.

하지만, page수가 많지도 않은 데 점점 build가 오래걸린다는 issue가 있다고 하고, 남들이 많이 하지 않는 거를 해보자!! 하는 마음과 Ruby 보다는 Go를 기반으로 한 Hugo 가 더 끌려 Hugo를 선택했다.

1. 첫 시작! Hugo 설치

github page를 이용하여 블로그를 만드는 것이기 때문에 따로 git 설치 과정은 생략한다.

Hugo install에 관한 공식 문서 를 보고 자신의 OS환경에 맞게 설치를 해주면 된다.

위의 링크를 통해 Linux나 macOS라면 명령어를 이용해서 쉽게 설치가 가능하다.

나는 windows를 사용하고 있고 따로 package sw를 사용하지 않기 때문에 Hugo 공식 github 을 통해 windows의 최신 버전의 zip파일을 이용해 설치했고 C:\Hugo\bin 디렉토리를 생성해서 이 폴더안에 다운받은 압축파일 해제했다.

1) 환경 변수 설정

1. 윈도우 검색창에 시스템 환경 변수를 검색 하고 실행시키기

2. 시스템 속성의 환경변수 클릭

1. 시스템 변수의 Path 더블 클릭

1. 새로 만들기를 클릭하여 아까 설치했던 C:\Hugo\bin 입력.

위와 같이 진행하거나 cmd를 통하여 $set PATH=%PATH%;C:\Hugo\bin 명령으로 환경변수를 추가하면 된다.

제대로 완료되었는지 확인 하고 싶다면 cmd를 통해 hugo version 으로 동작 확인.

2. 블로그 생성과 호스팅을 위해 Github repository를 2개 생성

repo를 두개 생성하게 되는데 한개는 hugo를 사용하여 블로그안에 채울 내용과 소스파일들을 저장하기 위한 repo를 만들어준다.

이 repo는 소스가 보여지는 게 싫다하면 private로 만들어도 무관하며 이름도 편한대로 만들면 된다.

다른 한개는 github page를 사용한 호스팅을 위해 USERNAME.github.io 라는 이름으로 생성하면된다.
이때 USERNAME 은 본인의 github name을 적으면 되고 이 repo는 무료로 호스팅을 위해서는 public으로 생성해야하고 private으로 생성하고 싶다면 Github pro 이상을 구매해야 한다.

3. 블로그의 컨텐츠들을 담을 파일 생성

hugo new site 파일명 왼쪽의 명령어를 사용하면 기본 hugo폴더의 뼈대가 자동적으로 생성이 되는데 원하는 파일 경로에 directory를 생성해주면 된다.

현재 cmd의 위치가 C:/Hugo 라면 이 폴더 안에 생성될 것이고 특정 경로를 지정하고 싶다면 hugo new site ../Users/파일명과 같이 파일명 앞에 경로를 추가해주면 된다.

나는 C:\Hugo 안에서 hugo new site blog 명령어를 통해 blog라는 폴더를 생성해주었다.

4. 테마 다운 및 설정

1. hugo 테마 둘러보기 사이트에 들어가서 마음에 드는 테마를 선택후 Download를 클릭.

2. 해당 테마의를 submodule에 추가한다.
   Download를 클릭하면 각 테마를 만든 사람의 github의 repo에 들어가지는데 repo에 어떻게 submodule를 추가하면되는지 나와 있다.

   나는 hugo-theme-docport 테마를 선택 했고 submodule 추가 과정은 git init > git submodule add https://github.com/vjeantet/hugo-theme-docport.git themes/hugo-theme-docport을 통해 추가했다.

3. config.toml 파일 수정 나와 똑같이 진행을 했다면 blog폴더 안에 config.toml 파일이 있을 텐데 이 파일을 통해 title이나 baseUrl, google analytics, theme 기본 설정등 해주게 된다.

   baseURL은 본인의 블로그 주소 ➡ Username.github.io를 설정 해주면 된다.

5. 파일 관리와 호스팅을 위해 github repo와 연결시켜주기

1) 처음에 만든 blog repo 연결

• cmd에서 C:\Hugo\blog로 이동한다.
• $ git remote add origin <본인의 첫번째만든 repo주소>

github repo주소를 모르겠다 하면 github 홈페이지의 본인 repo에 들어 가보면 code버튼을 클릭하고 위의 빨간색 동그라미 부분을 클릭하면 repo주소가 복사가 된다.

2) 두번째 만든 username.github.io repo 연결

• git submodule add -b master <두번째 만든 githbu.io repo주소> public 을 입력해주면 blog폴더 안에 public 폴더가 만들어지는 데 이 public폴더가 username.github.io 저장소와 연결 될 것이다.

6. 컨텐츠 생성

hugo new <파일명> 을 사용하여 업로드할 컨텐츠를 만들어 볼 수 있는 데 기본 파일구조가 테마별로 다르니 꼭 꼭 본인이 사용하는 테마의 repo를 잘 참조하자!!

컨텐츠가 생성이 되었다면 hugo server를 입력하면 http://localhost:1313/ 을 통해 확인해 볼 수 있다.

위의 명령어는 개발 모드로 실제 빌드는 되지 않고 배포를 위해 html 파일로 변환해주기 위해서는 아래와 같이 입력해주면 된다.

hugo -t <테마이름>

테마 이름은 blog/themes/ 아래 폴더 이름이 테마 이름이고, 빌드를 하면 public폴더에 html문서들이 생성된걸 볼 수 있다.

7. github page 이용해 업로드

개발모드가 아닌 실제 블로그를 업로드 해야하지 않겠는가?

업로드 순서는 다음과 같다.

1) username.github.io 에 push 하기

• $ hugo -t 테마이름 명령을 통해 테마가 적용된 블로그 내용을 public 폴더 내에 build 해준다.
• $ cd public 을 통해 public 디렉토리로 이동한다.
• $ git add . 수정된 파일들을 index에 올린다.
• $ git commit -m “커밋메세지” 변경 내용을 commit하고
• $ git push origin master commit을 통해 username.github.io에 upload

2) blog repo push 하기

위의 repo에만 올려도 포스팅은 되지만 코드 관리를 위해 이 repo도 push

• $ cd ..
• $ git add .
• $ git commit -m “커밋메세지”
• $ git push origin master

8. 컨텐츠 업로드 반 자동화 하기

github action을 이용하여 자동화를 하는 방법도 존재하는데, 나는 쉘스크립트를 이용하는 것이 더 편해 이방법으로 배포하고 있다.

아래의 코드를 deploy.sh로 저장하여 blog폴더 내에 두면 다음 부터는 컨텐츠 업로드시 일일히 타이핑하지 않고 deploy.sh “커밋메세지” 를 통해 자동으로 편하게 업로드 할 수 있고 굳이 deploy라는 이름이 아니어도 된다.

대신 .sh 확장자로 저장을 해야 쉘 스크립트로 저장이 되어 실행시킬 수 가 있다.

#!/bin/bash

# Build the project.
hugo -t <테마이름>

# github.io 레포 push위해 파일 경로 이동
cd public
# 충돌 방지를 위해 한번 pull
git pull origin master

# git내용들 추가
git add .

# Commit 바꾸기. git commit -m "원하는 커밋 메세지"를 입력하거나
# git commit만 입력시 커밋날짜를 메세지로 자동설정
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# github.io 레포에 push
git push origin master

# 상위 폴더인 blog도 push위해 경로 변경
cd ..

# blog 저장소 Commit & Push
# 충돌 방지를 위해 한번 pull
git pull origin master
git add .

msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

git push origin master

이제부터는 custom하는 내용으로 skip해도 무방하다.

9. custom domain 연결하기

github page를 이용해도 username.github.io가 아닌 개인의 도메인을 연결하여 사용할 수 있다.

나는 가비아를 통해 도메인을 구매했기 때문에 가비아 기준으로 설명한다.

1) My 가비아에 들어가 도메인 관리를 클릭 후 DNS 정보의 도메인 연결의 설정을 클릭.

나는 지금 설정을 해놓은 상태라 이렇게 추가가 되어 있는 데 레코드 수정을 통해 사진과 같이 추가해주면 된다.

TTL은 600!

2) 설정 후 본인의 username.github.io repo 에 돌아와 Settings를 클릭한다.

스크롤을 내리다 보면 Github pages 항목에 custom domain에 자기의 domain을 입력해 주고 Save를 클릭해주면 된다.

도메인이 적용되는 데 몇분의 시간이 소요 될 수 있고 Enforce HTTPS를 활성화 시켜주면 github 자체에서 Let’s Encrypt를 이용한 https를 무료로 적용 시켜 준다.

그리고 마지막으로 blog 폴더 내 config.toml파일의 baseURL을 내 도메인으로 바꿔주면 된다.

10. 댓글 기능 추가하기

github page는 정적 사이트 호스팅이다보니 자체적으로 댓글 기능을 제공하지는 않기 때문에 외부의 라이브러리를 사용해 추가를 해줄 수 있다.

유명한 라이브러리로 disqus가 있는 데 나는 disqus의 인터페이스가 이쁘지 않아서 다양한 댓글 라이브러리들 에서 찾다보니 utterances가 제일 마음에 들어 이걸 사용하기로 했다.

utterances 공식 문서 를 참고하면 theme도 설정가능하고 label도 설정가능 한데, 잘 모르겠다 싶으면 아래의 코드를 따라 해도 무방하다. (reop 경로는 바꿔주어야 한다.)

내가 선택한 테마는 github-light로 밝은 분위기가 깔끔해 선택했다.

• 댓글의 기능을 mapping 해줄 repo를 하나 생성 해준다.
  나는 comments라는 repo를 생성했다.
• 그 후 본인의 theme 폴더 내의 layouts/partials 안의 contents의 내용을 포함하는 body-contents 역할의 html파일을 찾아 blog/layouts/partials에 복사해와서 편집기를 통해 연다.
• 코드가 길게 있을 텐데 contents 끝 자락 부분의 아래나 footer 바로 윗 부분에 코드를 추가 해주면 된다.

<div style="margin-top:200px;">
  <script
    src="https://utteranc.es/client.js"
    repo="gowoonsori/comments"
    issue-term="pathname"
    theme="github-light"
    crossorigin="anonymous"
    async
  ></script>
</div>

이때 repo의 username과 repo이름은 바꿔줘야 한다!

누군가 댓글을 달면 해당 url 인덱스의 이름으로 연결시켜준 repo에 issue가 생기고 이 issue의 댓글을 보여주는 방식으로 작동한다.

Hugo 후기

한글 레퍼런스가 많이 없어 삽질을 많이 하긴 했지만 덕분에 hugo의 전체적인 파일 구조를 파악할 수 있어 손쉽게 내 입맛에 맞게 커스터 마이징을 할 수 있을 것 같다.

hugo를 처음 사용하시는 분들께 강조 하고 싶은 것은 본인이 선택한 테마의 문서 (설명서)를 잘 보자는 것이다.