GitHub Pages 블로그 로컬에서 미리보기 하기

개발 블로그를 GitHub Pages로 운영하면 좋은 점이 많지만, 글을 작성하고 매번 커밋해서 푸시한 뒤에 결과를 확인하려면 꽤 번거롭다. 특히 이미지 경로나 스타일이 잘 적용되었는지 확인할 때는 더 그렇다.

그래서 이번 글에서는 Jekyll 기반 블로그를 로컬에서 실행해보고, 실제 배포된 것처럼 미리보기 하는 방법을 정리해본다. 꼭 블로그 테마를 커스터마이징할 때뿐 아니라, 평소에도 빠르게 확인할 수 있어서 정말 유용하다.

왜 로컬 미리보기가 필요할까?

한 번이라도 “왜 이미지가 안 뜨지?”, “이 마크다운 왜 안 먹지?” 같은 문제를 겪었다면 공감할 거다.

• GitHub Pages 반영은 빠르면 몇 초, 느리면 수 분 소요

• 반영 오류가 있어도 GitHub에서 상세한 에러를 잘 안 알려줌

• 테마에 따라 마크다운 렌더링이 미묘하게 다를 수 있음

이런 문제를 줄이기 위해서라도 로컬에서 실행 → 확인 → 커밋 흐름이 익숙해지면 좋다.

Jekyll 로컬 서버 실행하기 (Windows 기준)

1. Ruby 설치

Jekyll은 Ruby 기반이기 때문에 먼저 Ruby를 설치해야 한다.

• 공식 사이트: https://rubyinstaller.org

• 설치할 때 “MSYS2 development toolchain” 옵션도 같이 설치 (체크박스 있음)

2. Jekyll 설치

Ruby 설치 후, 명령어로 Jekyll과 Bundler를 설치한다:

gem install bundler jekyll

블로그 프로젝트 실행

1. 터미널을 열고 블로그 폴더로 이동:

cd D:\dev\my-blog  # 내 블로그 디렉토리 경로

1. Gemfile이 없다면 생성:

bundle init

1. Jekyll 추가:

bundle add jekyll

1. 서버 실행:

bundle exec jekyll serve

1. 브라우저에서 접속:

http://localhost:4000

참고 사항

• 실제 GitHub Pages랑 100% 똑같진 않지만 거의 유사

• 테마 따라 CSS 깨지는 경우가 있을 수 있는데, _config.yml을 GitHub 환경이랑 맞춰두면 대부분 해결됨

• Ruby 환경 처음 세팅할 땐 살짝 귀찮긴 한데, 한 번 해두면 나중엔 진짜 편함

확인 포인트

• 이미지 경로: /images/ 식으로 잘 들어가는지

• 카테고리/태그/메타데이터가 올바르게 표시되는지

• 코드 블럭, 수식, 글머리 기호 등 렌더링 확인

• 커스터마이징한 _config.yml 설정이 반영되는지

마무리

글 하나 작성할 때마다 GitHub에 올리고 기다리는 시간이 누적되면 생각보다 피로도가 크다. 로컬에서 바로 확인할 수 있는 환경을 만들어두면 실수를 줄이고, 수정 작업도 훨씬 빠르게 할 수 있다.

Jekyll 기반 GitHub 블로그를 운영한다면, 이 세팅은 거의 필수에 가깝다. 테마를 커스터마이징하거나 마크다운을 자주 수정하는 사람이라면 더더욱 그렇다.

특히 마크다운 이미지 경로나 스타일 깨지는 거 자주 겪는다면, 로컬에서 먼저 돌려보는 거 강력 추천!!.