기술 블로그 만들기 [Github Pages, Hugo]

• Mon, Aug 1, 2022
• 읽는 시간 6분

사용하고 싶고, 관리하고 싶은 기술 블로그 만들기

• Github pages
• Hugo
• Customization
• Utterances

1. Intro.

기존에 블로그를 만들어 공부한 내용이나 독서 기록 용도로 블로그를 운영하고 있었는데, 요즘 기록하는 빈도도 떨어지고 관심도도 떨어져 가는 것 같았다. 이를 극복하고자 블로그에 작은 변화도 주고, Github action 등의 설정을 하면서 과정을 좀 정리해 보려고 한다.

이 글을 정리하는 시점에 내 블로그는 이미 Github pages로 구축되어 있었고, 테마도 잘 적용되어 있었다. 하지만 기술 블로그보다는 독서록이 되어가고 있었다. 그리고 Hugo를 이용하면서 블로그에 글을 쓰는 과정이 번거로워진 부분도 있었다. 변화를 주고 싶었다. 그래서 블로그에 들어가 보면 “아 기술 블로그”구나 하는 요소를 추가해 보고 글을 쓰는 과정도 Github action을 통해 좀 더 편하게 바꿔 보려고 한다. 그리고 더불어 그 과정과 이슈를 기록으로 남겨본다.

2. 플랫폼 선택하기

현재 IT 직군의 종사하시는 분들, 또는 IT 직군으로 커리어를 만들어가는 학생분들의 기술 블로그 운영 지원을 위한 다양한 플랫폼들이 존재한다. Medium, Velog 등 개발자 친화적이고 편하게 사용할 수 있는 플랫폼이 최근에 떠오르고 있고, 워드프레스와 같은 CMS를 지원하는 플랫폼, Github page을 이용하여 정적 사이트 생성을 도와주는 툴을 사용할 수도 있다.

• CMS: Contents Management System, 말 그대로 웹사이트에 필요한 contents 들을 관리하는 시스템으로 이러한 콘텐츠를 기반으로 다양한 웹페이지를 생성하는 동적인 웹사이트 생성 동작을 위한 데이터 베이스 역할을 한다.
• 정적 사이트란 웹사이트가 동작하기 위한 모든 소스와 데이터들이 생성이 되어 있고, 이를 단순히 호스팅 하는 방식의 사이트를 말한다. 관리가 용이하고 속도가 빠르다는 장점이 있다.

나는 Github pages로 관리하면서 최근 정적 사이트 생성 툴 중 비교적 빠르고 최신 언어인 go를 이용해 만들어진 hugo를 이용하고 있다. 내가 처음 Github page로 블로그를 개설할 때에는 Jekyll이 많이 사용되어 왔었는데 1~2년 전 Hugo 가 빠른 정적 사이트 생성기로 떠오르면서 빠르게 갈아탔다.

정적 사이트 생성기에 대한 최신 통계는 Jamstack에서 확인해 볼 수 있다.

정적 사이트 생성기와 Github page를 이용한 블로그 구축은 손이 많이 가는 선택지이다. 하지만 그만큼 자유도가 높고 관련 자료들도 풍부하여 해볼 가치가 있는 선택이었다. 웹 애플리케이션이나 html, CSS, JS 등 을 다루는 프런트엔드 기술에 대한 간접적인 이해에 도움이 되는 부분도 많았다. 또한 검색 최적화, 통계, 광고 수익 창출 등 블로그 운영에 있어 확장성이 좋다.

그리고 Github 관리와, 블로그 관리를 같이 할 수 있다는 점도 다른 플랫폼과 차별화되는 장점이라고 본다. 그리고 개발자의 눈에는 github로 blog를 만들어 운영하는 것이 멋있어 보인다고 한다. 개발하는 것처럼 블로그를 만드는 부분이 현업에서 기술 문서를 개발하는 과정과 유사하다고도 볼 수 있을 것 같다.

최근에는 Notion을 블로그로 많이 쓰거나, CMS로 사용하는 것을 볼 수 있는데, 사용해 보니 아직은 API가 편하거나 보기 좋게 만들기 위한 theme 지원 등에서 부족함이 많았다. 사실 전에 잠깐 관리를 해 보았는데 콘텐츠를 보기 좋게 하거나 블로그 레이아웃을 잘 꾸미기에는 손이 너무 많이 가서 지금의 상태로 돌아오게 되었다.

내 블로그 역사: 네이버 블로그 -> Github + jekyll -> Github + hugo -> notion + node.js -> Github + hugo

3. hugo 블로그 개발하기

Hugo는 Go 언어로 만들어진 static site generator이다. 빠르고 유연한 정적 사이트 생성을 위해 만들어졌다고 한다. 실제로 이전에 사용하던 Jekyll 보다 훨씬 쾌적한 사용성을 느끼고 있다.

1. 개발 환경 만들기

   Windows11 에서 환경을 구축하면, 인코딩 이슈로 사이트 생성이 적절하게 수행되지 않는 문제를 겪었었다. 하지만 대부분의 사용자라면 어떤 플랫폼을 사용하더라도 개발하는 데 있어 큰 문제가 있을 것 같지는 않다. 다만 내가 사용하는 anatole theme을 사용하는 사용자라면 Linux 환경을 이용하기를 권장한다.

   • Hugo 설치: https://gohugo.io/getting-started/installing/

     brew install hugo
     

2. Github repository 만들기

   Hugo를 이용한 블로그 운영을 위해서 보통 2개의 repository를 만들어서 운영하지만 나는 theme를 관리하기 위한 repository를 추가로 만들어서 운영하였다.

   1. blog

      Hugo를 이용한 블로그의 content 관리, blog 설정 및 theme를 관리하는 역할을 한다. 여기에서 정적 사이트를 생성한다. 나는 private으로 관리하고 있다.

   2. username.Github.io

      blog에서 생성한 정적 사이트를 호스팅 해주는 역할을 한다. Github pages를 통해서 [Github.io](http://user name.Github.io)로 끝나는 멋진 도메인의 블로그를 가질 수 있게 해준다.

      • Github pages 설정
        1. repository 생성
        2. Settings 진입
        3. Pages 진입
        4. Source → Deploy from a branch 선택
        5. Branch → master, /(root) 선택

   3. theme

      Hugo는 다른 사용자들이 만든 theme를 손쉽게 사용할 수 있는 기능을 지원한다. 나도 anatole이라는 미니멀한 theme를 사용하고 있다. theme를 잘 만들어놔서 설정 변경만으로도 충분히 사용할 만한 theme이다. 하지만 theme의 변경 및 수정사항이 필요할 때, 좀 더 많은 커스텀 기능을 원할 때에는 fork 하여 나의 repository를 만들어서 사용하는 것이 좋다. 이렇게 사용하는 것이 추후에 기능 추가 등의 PR을 하는 등 더 확장 가능하다고 생각한다.

   [blog], [username.github.io], [your_theme] 세 가지의 repository가 준비되었다면, 초기 셋업을 아래와 같이 해준다.

   hugo new site blog # blog -> your repository name
   cd blog
   git init
   git submodule add https://Github.com/your_name/your_theme.git themes
   git commit -m "init"
   git remote add https://Github.com/your_name/blog
   git push origin master
   

   위와 같이 셋업을 하면 [blog] repository에 [your_theme] repository 가 themes 폴더 아래에 submodule로 추가가 된다. 그리고 [blog] repository의 초기 코드가 remote 저장소에 저장이 된다.

   위의 과정을 거치면 기본적인 설정이 완료되었고 사이트가 잘 생성되는지 아래의 명령어를 통해 확인할 수 있다.

   hugo server --themesDir theme # -> local server를 동작시킨다.
   hugo --themesDir theme        # -> public 폴더에 정적 사이트(코드)가 생성된다.
   

   hugo server를 통해서 local server를 동작시키면 현재 생성될 사이트를 http://localhost:1313 주소로 들어가서 확인해 볼 수 있다. hugo 명령어를 통해 public 폴더에 생성된 사이트를 [username.Github.io] 저장소로 올리면 Github pages를 통해 이를 hosting 하여 “username.Github.io” 주소를 통해 생성된 사이트를 확인해 볼 수 있다. 이 과정이 조금은 번거롭기 때문에 뒤에서 Github action을 통해 자동화할 것이다.

   여기까지가 기본적인 설정 방법이고, Fork 한 theme을 적용하는 방법은 뒤에서 좀 더 설명해 본다.

3. Hugo theme 적용하기

   나는 anatole theme를 이용하였고 적용하는 방법 역시 https://Github.com/lxndrblz/anatole/wiki 여기에 잘 정리되어 있다.

   만약 theme를 그대로 사용하고자 하면 route1 방식을 이용하면 된다. 하지만 나의 경우처럼 개인 repository 에 fork 한 수정된 theme을 사용하고자 한다면 route2 방식으로 사용해야 한다.

   [blog] repository 초기 설정을 해주면서 theme을 추가해준 뒤 config.toml 파일에 theme 이름을 추가해주면 된다.

   relativeURLs = true
   baseURL = 'https://username.Github.io/'
   languageCode = 'ko'
   title = 'My New Hugo Site'
   theme = "anatole"
   

4. Utterances 적용하기

Utterances는 블로그 등에 댓글기능을 지원하는 서비스로 독특하게도 댓글을 작성하면 Github의 Issue 로 생성해준다. 따라서 댓글 작성을 위해서는 Github 계정이 필요하지만, 개발자 친화적인 Github Issue와 연동해준다는 부분이 상당이 멋있다. 또 가볍고, 광고가 없다는 부수적인 장점도 있었다. 기존에는 Disqus라는 서비스를 이용하고 있었는데 광고가 붙는 부분이 은근히 신경쓰였었다. 적용 방법도 상당히 간단한 편이다. 홈페이지(https://utteranc.es/)에서 나와 있듯이, 댓글을 이슈로 관리할 public repository를 준비하고, 몇가지 설정을 입력하면 댓글을 만들어주는 스크립트를 얻을 수 있다. 이를 웹페이지에 삽입하면 댓글창이 생성된다. 내가 사용하고 있는 Hugo Theme 에서는 Utterances를 설정으로 지원하고 있어서 더욱 간단히 설정 파일만 수정하여 댓글 기능을 추가하였다.

[params.utterances]
repo = "githubuser/reponame"
issueTerm = "pathname"
theme= "preferred-color-scheme"

5. Github action으로 자동 배포하기

(작성 예정)

6. hugo theme custom 하기 - taxonomy cloud 만들기

현재 블로그가 꽤 마음에 들었지만 한 가지 아쉬운 점이라면, 내가 이 블로그에 어떤 글들을 많이 올려왔는지 한눈에 들어오지 않은 점이었다. 최근에 올린 글이 상단에 노출되어 이전 기록들을 볼 수가 없다. 모든 내용들을 분류하기에는 번거로운 트리 구조가 생길 것 같아서 단순히 tag로만 관리하는 지금의 상태의 문제이다. 이를 해결하고자 tag 모음을 시각화해주는 텍스트 클라우드를 사이드바에 추가하고자 했다.

(작성 예정)

7. 회고

• 사용해 본 적 없는 언어로 새로운 기능을 추가한 부분은 뿌듯하다. 사실 언어가 중요한 것이 아니라 문제를 찾아내고 만들어내고 해결해 나가는 과정이 중요한 것이라는 생각을 다시 한번 해본다.
• 언어와 Hugo 시스템에 좀 더 익숙했다면 PR도 해볼 수 있을 것 같은데 이 부분이 조금 아쉽다. 나중에 기회가 된다면, author에게 도움을 요청해서 PR까지 진행해 보고 싶다.

Reference

• https://Github.com/lxndrblz/anatole
• https://gohugo.io/getting-started/quick-start/
• Utterances