Hugo 블로그로 이주하기

2026. 03. 29. 18:48 • 읽는데 6분

기존 Notion Oopy 기반 varofla 블로그 — Oopy로 만들었던 기존 varofla 블로그

한참 Notion 뽕(?)에 취해있던 시절, 또 다른 재미난 거 할 거 없나 하다가 Notion으로 블로그를 생성하는 Oopy로 블로그를 만들게 되었습니다. 십여 년간 사용해 오던 네이버 블로그의 카테고리가 너무 난잡해지기도 했고, 무엇보다 흑역사를 묻어둘 겸~~신분새탁~~ 이기도 했죠.

프론트와 백엔드를 직접 깎지 않아도 깔끔한 블로그를 쉽게 만들어낼 수 있어 상당히 만족하며 사용하고 있었습니다.

하지만 약 3년간 Oopy를 사용해 오며 점점 불만이 쌓이게 되었습니다. Oopy의 너무나도 느린 로딩속도와 자잘한 렌더링 버그들, 그 와중에 Notion은 수시로 멈추고 버벅이고..

조금 더 가벼운 대안이 없나 하던 중 개인적인 메모들은 모두 Obsidian으로 이주하며 Notion을 사용하는 빈도가 점점 줄어들게 되었습니다.

그러던 어느 날 자료를 찾던 중 어느 블로그를 발견하게 되었습니다. 빠른 로딩 속도에 깔끔한 UI.. 그리고 뭔가뭔가 Markdown스러운 느낌이 들었습니다. 어떻게 만들어진 블로그인가 알아보니 Hugo로 만들어졌다는 것을 알게 되었습니다.

아무리 Markdown 기반이라 하더라도 Notion과 1:1호환이 불가능한 건 확실해 보입니다. 글이 더 쌓이기 전에 하루빨리 블로그를 옮기기로 했습니다.

Hugo? #

The world's fastest framework for building websites

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes …

gohugo.io

Hugo는 Markdown 파일을 입력해 정적 페이지(HTML, CSS, JS)를 만들어주는 정적 페이지 생성기라 합니다.

오픈소스 기반에 수천 개의 활발한 커밋, 그리고 테마 시스템을 제공하기 때문에 HTML/CSS에 친숙하지 않아도 쉽게 시작할 수 있다는 게 큰 장점으로 보였습니다.

자료를 조금 더 찾던 중 국내의 어느 개발자분께서 멋진 테마를 공유하고 계셨는데요, 이 테마를 활용해 블로그를 만들어보기로 했습니다.

Hugo 세팅 #

매달 100kWh에 가깝게 전기를 먹어대는 서버도 있겠다, 월 결제를 줄이고 직접 블로그를 호스팅하기로 했습니다. Oopy 대센 Self-host 하게 되면 매달 만원 정도 전기세가(???) 아껴지는 셈이네요.

Docker로 Hugo 사용하기 #

로컬 환경을 최대한 깔끔하게 유지하기 위해 Hugo를 PC에 설치하기보다는 서버의 VM에 설치해서 VM에서 빌드하기로 했습니다. 블로그와 관련된 모든 파일을 저장하고 백업하기 위해 NAS와 연결된 /mnt/tank 디렉토리 아래에 blog디렉토리를 만들었습니다.

Hugo Docker Images

Automated and up-to-date community Hugo Docker images, with various tags from minimalist to comprehensive, such as …

docker.hugomods.com

물론 Hugo 설치 역시 VM에 직접 설치하지 않고 Docker 컨테이너로 실행하기로 했습니다. 비공식 Hugo Docker 이미지인 hugomods/hugo를 사용합니다.

우선 /mnt/tank/blog 디렉토리 아래에 블로그 프로젝트를 만들었습니다. 여기서는 프로젝트 이름으로 project를 사용했습니다.

bash

docker run --rm -it \
  -v /mnt/tank/blog:/src \
  -w /src \
  hugomods/hugo:debian-non-root-0.158.0 \
  hugo new site project

명령을 실행하고 나면 /mnt/tank/blog/project 디렉토리가 만들어지고, 안으로 들어가 보면 Hugo 블로그를 위한 각종 파일들이 자동으로 생성된 것을 확인할 수 있습니다.

Hugo 스크립트 생성 #

작업을 편리하게 하기 위해 원하는 명령과 함께 Hugo 컨테이너를 실행하는 스크립트를 만들었습니다.

편의를 위해 블로그 프로젝트 위치를 하드코딩했습니다. SITE_DIR를 참고해 주세요.

bash

#!/usr/bin/env bash

SITE_DIR="/mnt/tank/blog/project"
IMAGE="hugomods/hugo:debian-non-root-0.158.0"

docker run --rm -it \
  -v ${SITE_DIR}:/src \
  -w /src \
  ${IMAGE} \
  hugo "$@"

SeoTax 테마 #

Hugo 서택스(SeoTax) 테마 제작기 - 동적 렌더링으로 확장된 검색

Hugo 서택스(SeoTax) 테마는 동적 렌더링을 활용해 정적 페이지의 한계를 극복하고, 고급 검색 및 분류(Taxonomy) 기능을 제공합니다. 테마의 설계 목적 및 주요 기능 …

minyeamer.github.io

테마로는 Minystory 블로그의 Minyeob Kim 님이 제작한 SeoTax 테마를 사용했습니다.

Hugo를 세팅하던 중 자료를 찾다가 우연히 발견한 블로그인데요, 너무 멋진 테마에 반해서 찾아보다 보니 세상에.. 직접 만든 테마를 GitHub에 오픈해 두셨더라고요. Hugo에서 잘 지원하지 않는 2차 카테고리를 지원하는 점이 가장 컸고, 그 밖에도 mac 스타일의 코드블럭이나 깔끔한 북마크 등 다양한 기능을 지원하고 있었습니다.

위의 블로그 포스팅을 참고해 테마를 추가했습니다. 덕분에 너무 행복하게 블로그를 만들고 있습니다. 👍

포스팅 마이그레이션 #

제일 답이 없는 부분입니다. Notion에서만 지원하는 Markdown 기능(이미지 양옆 배치 등)과 Oopy에서 지원하는 기능(HTML 삽입하기, SEO 양식 등)을 수동..으로 하는 건 답이 없고, LLM과 씨름하며 마이그레이션 코드를 작성해 처리했습니다. 오른쪽에 ChatGPT, 왼쪽에 Gemini 띄워두고 잘 작동하는놈 코드로.. 번외로 Gemini가 압승했습니다.

그럼에도 불구하고 깨진것들이 많아서 이건 천천히 해결해 보려 합니다.

테마 커스터마이징 #

varofla/hugo-seotax at mod

Modification of the Seotax Hugo theme. Contribute to varofla/hugo-seotax development by creating an account on GitHub.

github.com

원판 테마 자체도 한눈에 반할 정도로 너무 좋았지만 개인적으로 추가되었으면 하는 부분이 있어, Fork한 후 커스터마이징을 진행했습니다.

HTML이나 CSS는 쌩초보기에.. LLM의 도움을 많이 받았습니다. 항상 Option+Space 키로 ChatGPT를 호출해서 질문을 날리곤 했는데, 최근에 Codex의 존재를 알게되어서 사용해 봤습니다. 프로젝트 폴더 전체를 스켄하며 코드를 짜주는게 정말 신기하면서도 한편으로는 무섭네요. 행복 코딩도 이제 얼마 남지 않은 것 같습니다..

Comentario 댓글 #

Comentario - Comments. Easy.

Add comments to your web page or blog in a matter of minutes.

comentario.app

SeoTax 순정 테마에서는 Disqus 댓글을 사용했습니다. 항상 에드가드가 처리해 주고 있어서 잘 몰랐는데, 이게 광고를 엄청나게 띄우고 있더라고요. 기존 블로그처럼 giscuc를 사용할까 하다가 오픈소스 Self-host 댓글 플랫폼인 Comentario를 사용해 보기로 했습니다. Google, GitHub 등의 SSO를 지원하는 게 괜찮아보였습니다.

layouts/_partials/footer/comments.html의 기존 Disqus 내용을 파내고 Comentario의 Docs를 참고해 아래 코드를 집어넣었습니다. 추가적으로 Comentario의 테마 설정이 블로그의 테마 스위치 버튼을 따라가도록 하는 Javascript를 추가했습니다.

html

<comentario-comments id="comentario-comments"></comentario-comments>
<script>
(function() {
  const commentsEl = document.getElementById('comentario-comments');
  if (!commentsEl) return;

  function getTheme() {
    const theme = document.documentElement.getAttribute('data-theme');
    return theme === 'dark' ? 'dark' : 'light';
  }

  function syncComentarioTheme() {
    commentsEl.setAttribute('theme', getTheme());
  }

  // Set the initial theme before Comentario initialises.
  syncComentarioTheme();

  document.addEventListener('DOMContentLoaded', function() {
    syncComentarioTheme();

    window.addEventListener('site-theme-changed', syncComentarioTheme);

    const observer = new MutationObserver(function(mutations) {
      for (const mutation of mutations) {
        if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') {
          syncComentarioTheme();
        }
      }
    });

    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ['data-theme']
    });
  });
})();
</script>
<script defer src="https://comentario.varofla.com/comentario.js"></script>

더 매끄러운 이미지 줌 #

순정 테마에는 이미지를 클릭하면 커지는 기능이 있기는 했지만, 부드러운 모션이 없다 보니 어색하기도 했고 특히나 모바일에서 클릭하게 되면 이미지가 90도 돌아가 버리는 현상이 있었습니다. 좌우로 넓은 사진을 조금이나마 더 잘 보이도록 해주는 기능인 것 같았지만 개인적으로는 인터페이스 경험이 깔끔하지 않아보였습니다.

francoischalifour/medium-zoom

🔎🖼 A JavaScript library for zooming images like Medium - francoischalifour/medium-zoom

github.com

나은 대안이 없나 하다가 medium-zoom을 알게 되어 적용해 보게 되었습니다.

부드럽게 잘 작동하는 모습입니다. 상당히 마음에 드네요.

medium-zoom GitHub 리포지토리 README중 일부 — medium-zoom - Attributes [링크]

한편 medium-zoom은 클릭할 때 표시할 이미지를 따로 표시하는 기능이 있었습니다. 평소에는 용량이 줄어든 이미지를 표시하고 클릭했을 때만 원본 이미지를 표시하도록 활용해 보았습니다. 물론 ChatGPT와 함께.. Hugo Image 숏코드에서 페이지에 박히는 크기로 이미지 리사이징을 하고 zoom 시점의 원본 이미지는 줌 시점의 이미지 src인 data-zoom-src로 넣어주게 했습니다.

마지막으로 Cloudflare를 앞단에 붙이고 있다 보니 원본 이미지 로딩 속도가 조금 느려서 스피너를 붙여봤습니다.

자연스러운 카테고리 표시 #

SeoTax 테마의 계층 카테고리는 정말 강력한 기능입니다. 카테고리에 들어갔을 때 2차 카테고리를 펼쳐주면 조금 더 자연스럽지 않을까 해서 마찬가지로 채찍피티채찍질로 포스팅이나 카테고리로 들어가면 왼쪽의 카테고리가 자동으로 펼쳐지도록 했습니다.

기타 수정사항 #

이 외에도 자잘한 수정을 많이 진행했습니다.

CSS 관련
- 이미지 라운딩
- 이미지 캡션 중앙정렬, 캡션 내부에서 마크다운 지원
- Notion 스타일 링크
- Mermaid 그래프 중앙정렬
버그 수정
- 1줄짜리 코드블럭 복사 불가 버그 수정
- 코드블럭 스니펫 2중 스크롤바 생성 수정
- 북마크 fetch 실패 시 빌드 실패하는 현상 수정
기타
- 북마크 fetch 실패 시 failover 뷰 적용
- 부드러운 목차 스크롤

마무리 #

HomeLab을 키우며 언젠가는 블로그도 Self-host 해야 하지 않을까 막연하게 생각하고 있었는데, 이걸 드디어 하게 됐습니다.

본문에도 잠시 언급했듯이 깨진 링크나 Markdown 문법들이 여전히 많아 한동안은 꽤나 고생하게 될 것 같습니다. 그럼에도 불구하고 블로그 로딩 속도가 너무 빨라서 마음에 듭니다.

기존 Oopy 블로그에서는 Notion이 편리한 에디터 역할을 해주었는데요, Hugo 블로그에서는 딱히 사용할 만한 에디터가 없다 보니 조금 불편한 감이 없지 않아 있습니다. SeoTax 테마를 만든 블로거분은 VSCode Extension을 직접 만들어 이미지 업로드를 자동화했는데, 저도 이런 걸 한번 만들어봐야 할 것 같습니다.

끝으로 멋진 SeoTax 테마를 만들고 공유해 주신 Minyeob Kim 님께 감사 인사드립니다 🙂