GitHub Pages와 Jekyll로 기술 블로그를 구축했다. 로컬 개발은 Docker로 Ruby/Jekyll 환경 없이 돌리고, main 브랜치에 push하면 GitHub Actions가 자동 빌드해서 배포하는 구조다.

왜 GitHub Pages + Jekyll인가

Velog, Tistory 등 기존 플랫폼 대신 GitHub Pages를 선택한 이유는 하나다. 포스트 전체가 Git 히스토리로 관리되고, 자유롭게 커스터마이징할 수 있다.

Jekyll은 Markdown 파일을 정적 HTML로 변환해준다. 서버 없이 GitHub Pages에 올리면 무료로 호스팅된다.

테마 선택 — jekyll-theme-yat

직접 CSS를 짜는 건 시간이 걸려서 오픈소스 테마를 썼다. jekyll-theme-yat(jeffreytse)는 다크모드 자동 전환, 카테고리/태그 페이지, 페이지네이션이 기본 포함되어 있어서 선택했다.

_config.yml에 remote_theme으로 설정하면 별도 파일 복사 없이 GitHub에서 직접 불러온다.

# _config.yml
remote_theme: "jeffreytse/jekyll-theme-yat"

title: HyeongJin`s Development Blog
email: hjkim7153@gmail.com
author: projectSylas
url: "projectSylas.github.io"

night_mode: "auto"  # 19:00~07:00 자동 다크모드

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-paginate
  - jekyll-spaceship

Gemfile에는 github-pages gem을 추가한다. GitHub Pages가 지원하는 플러그인 버전을 맞춰준다.

# Gemfile
source "https://rubygems.org"
gemspec

gem 'jekyll'

group :jekyll_plugins do
  gem "github-pages"
end

gem 'webrick', '~> 1.8'

Docker로 로컬 개발 환경 구성

Jekyll은 Ruby 환경이 필요하다. macOS에서 Ruby 버전 관리하다 보면 gem 충돌이 자주 난다. Docker로 깔끔하게 해결했다.

# docker-compose.yml
version: '3'
services:
  jekyll:
    image: jekyll/jekyll:latest
    command: jekyll serve --watch --force_polling --host 0.0.0.0
    ports:
      - "4000:4000"
    volumes:
      - .:/srv/jekyll

# 로컬 서버 실행
docker-compose up

# http://localhost:4000 에서 확인

--watch --force_polling 옵션이 중요하다. --watch만 쓰면 macOS의 파일시스템 이벤트가 Docker 볼륨에서 감지가 안 돼서, --force_polling으로 주기적으로 변경 여부를 체크하게 한다.

포스트 파일을 수정하면 자동으로 재빌드된다. 브라우저를 새로고침하면 바로 확인 가능.

포스트 작성 — frontmatter 형식

_posts/ 디렉토리에 YYYY-MM-DD-슬러그.md 형식으로 파일을 만든다.

---
layout: post
title: 포스트 제목
subtitle: 부제목
author: HyeongJin
date: 2024-03-19 09:00:00 +0900
categories: Backend
tags: [Python, Django, backend]
sidebar: []
published: true
---

본문 내용 (Markdown)

published: false로 설정하면 빌드에서 제외된다. 초안 작성 시 유용하다.

GitHub Pages 배포

projectSylas.github.io 레포의 main 브랜치에 push하면 GitHub Actions가 자동으로 Jekyll 빌드 → GitHub Pages 배포를 처리한다.

git add _posts/2024-03-19-new-post.md
git commit -m "feat: add new post"
git push origin main

push 후 1~2분이면 반영된다. GitHub Actions 탭에서 빌드 로그를 확인할 수 있다.

Google Analytics 연동

_config.yml에 GA4 측정 ID를 추가하면 jekyll-theme-yat가 자동으로 스크립트를 삽입해준다.

google_analytics: G-XXXXXXXXXX
enableDNT: "true"

운영하면서 겪은 것

_config.yml을 수정한 경우 Docker 컨테이너를 재시작해야 반영된다. --watch가 _config.yml 변경은 감지하지 않는다.

future: true 설정을 안 하면 미래 날짜 포스트가 빌드에서 제외된다. 날짜를 미리 잡아두고 작성할 때 필요한 옵션이다.

포스트 날짜는 date: frontmatter 기준으로 정렬되므로, 파일명 날짜와 frontmatter 날짜를 일치시켜야 헷갈리지 않는다.