GitHub Pages + Notion으로 무료 기술 블로그 만들기

Claude와 대화한 내용을 자동으로 블로그에 발행하는 시스템을 직접 구축해봤다. 도메인은 기존에 사용 중인 zeclab.kr을 활용해 blog.zeclab.kr로 운영하기로 했다.

전체 구조

Claude 대화 → Notion 정리 → GitHub 자동 동기화 → blog.zeclab.kr 발행으로 이어지는 파이프라인이다. 모든 구성 요소가 무료이고, Notion에서 글을 작성한 후 Published를 체크하면 자동으로 블로그에 반영된다.

사용한 스택

  • Hugo — 정적 사이트 생성기. 빌드가 빠르고 한국어를 잘 지원한다.
  • PaperMod — Hugo 테마. 깔끔하고 다크모드를 기본 지원한다.
  • GitHub Pages — 무료 호스팅. 커스텀 도메인 연결도 가능하다.
  • GitHub Actions — 자동 빌드 및 배포. Notion 동기화도 여기서 처리한다.
  • Notion — CMS 역할. 글 작성과 발행 여부를 관리한다.

설정 과정

1단계 — GitHub 저장소 생성 및 Hugo 설정

zeclab-blog 저장소를 생성하고 hugo.yaml 설정 파일과 GitHub Actions 워크플로우 파일을 추가했다. PaperMod 테마는 GitHub Desktop을 통해 로컬에서 업로드했다.

한 가지 주의할 점은 PaperMod 최신 버전이 Hugo v0.146.0 이상을 요구한다는 것이다. deploy.yml에서 hugo-version을 0.147.0으로 지정해야 빌드가 정상적으로 작동했다.

Github_260526.png

2단계 — 도메인 연결

카페24에서 DNS 관리 → 별칭(CNAME) 관리로 이동해 아래 레코드를 추가했다.

  • 타입: CNAME
  • 호스트명: blog
  • 값: zeclab5.github.io

GitHub Pages 설정에서 커스텀 도메인에 blog.zeclab.kr을 입력하고, Hugo 빌드 시 CNAME 파일이 자동 생성되도록 static/CNAME 파일도 추가했다.

3단계 — Notion 연동

Notion에서 데이터베이스를 생성하고 아래 속성을 추가했다.

  • 이름 (제목)
  • Published (체크박스)
  • Date (날짜)
  • Tags (멀티 선택)
  • Slug (텍스트)

Notion API 통합을 생성해 액세스 토큰을 발급받고, GitHub Secrets에 NOTION_TOKEN과 NOTION_DATABASE_ID를 등록했다. notion-to-hugo.js 스크립트가 Published가 체크된 글을 가져와 Hugo 마크다운 파일로 자동 변환한다.

notion_260526.png

글 발행 방법

  1. Notion → ZECLAB Blog 데이터베이스 → 새 페이지
  2. 제목, 날짜, 태그, Slug 입력 후 본문 작성
  3. Published 체크
  4. GitHub Actions → Run workflow 클릭
  5. 1~2분 후 blog.zeclab.kr 확인

매시간 자동 실행 스케줄도 설정되어 있어서 수동 실행 없이도 최대 1시간 안에 자동 반영된다.

blog_260526.png

이미지 업로드 방법

Notion에 이미지를 직접 업로드하면 임시 URL이 생성되어 시간이 지나면 만료된다. 블로그에 이미지를 안정적으로 표시하려면 GitHub에 직접 올리는 방법을 사용한다.

① 파일 탐색기에서 아래 경로로 이동:

문서 > GitHub > zeclab-blog > static > images

images 폴더가 없으면 새로 만든다.

② 사용할 이미지 파일을 images 폴더에 복사

③ GitHub Desktop 열기 → Summary에 Add images 입력 → Commit to main → Push origin 클릭

④ 업로드 완료 후 이미지 URL:

https://blog.zeclab.kr/images/파일명.jpg

⑤ Notion 본문에서 /이미지 → URL 탭에 위 주소 입력

이렇게 하면 블로그에 이미지가 영구적으로 표시된다.

마치며

설정 과정에서 Hugo 버전 문제, PaperMod 테마 파일 누락, Notion API 버전 충돌 등 여러 문제가 있었지만 하나씩 해결했다. 코드 없이 GitHub UI와 GitHub Desktop만으로 대부분의 설정을 완료할 수 있었다는 점이 인상적이었다.

앞으로 Claude와 나눈 AI·기술 관련 대화를 정리해 이 블로그에 꾸준히 올려볼 계획이다.