Jekyll 블로그를 로컬에서 실행하기

요며칠 블로그에 글을 몇 개 작성하면서, 수정사항이 블로그에 반영되는걸 보고싶을 때마다 커밋과 빌드를 기다리는 과정이 번거로웠다. 쓸데없이 커밋이 많아지는 것도 피하고 싶어, 로컬에서 수정사항을 확인하고자 로컬 실행 방법에 대해 알아보았다.

필요 도구 설치

chruby 및 ruby-install 설치

chruby 는 Ruby 의 버전 관리 도구, ruby-install 은 Ruby 의 설치 도구이다.

brew install chruby ruby-install

Ruby 설치

# 설치 전 버전 확인
ruby -v
> ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22]

# 설치
ruby-install ruby 3.4.1

# .zshrc 수정 (.zshrc 가 있는 루트 디렉토리에서 실행할 것)
echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.4.1" >> ~/.zshrc # run 'chruby' to see actual version

# .zshrc 읽어들이기
source .zshrc

# 설치 후 버전 확인
ruby -v
> ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin22]

Jekyll 설치

sudo gem install jekyll
# sudo가 없으니 아래와 같은 permission 에러가 발생했기에, sudo로 설치한다.
# You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

로컬 빌드

bundle install 실행

➜  wonderminah.github.io git:(master) ✗ bundle install
> Bundle complete! 13 Gemfile dependencies, 53 gems now installed.

Jekyll 블로그를 로컬로 실행

➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll serve

http://localhost:4000/ 로 접속해본다.

[2025-04-03 15:34:08] ERROR `/assets/css/main.css' not found.
[2025-04-03 15:34:08] ERROR `/assets/js/main.min.js' not found.

왜이래…

➜  wonderminah.github.io git:(master) ✗ ll _site/assets/css/main.css
➜  wonderminah.github.io git:(master) ✗ ll _site/assets/js/main.min.js

로컬 프로젝트의 _site 폴더 아래에, assets/css/main.css 나 /assets/js/main.min.js 는 실제로도 존재하지 않았다. 빈 파일로 작성 touch main.css 해보니 에러가 발생하지 않는 것으로 보아, 위의 파일이 없어서 생긴 에러는 맞는데, 왜 없는 것인가.

Trouble Shooting 1 (미해결): jekyll 을 업데이트 해보기

➜  wonderminah.github.io git:(master) ✗ gem list
jekyll (4.4.1)
jekyll-sass-converter (3.1.0)
jekyll-watch (2.2.1)

➜  wonderminah.github.io git:(master) ✗ gem update jekyll
> Gems already up-to-date: jekyll

애초에 최신 버전이었다.

Trouble Shooting 2 (미해결): 기존 캐시를 지우고 다시 빌드하기

➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll clean
➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll build
➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll serve

해결되지 않았다.

Trouble Shooting 3 (미해결): _site 폴더를 지우고 다시 빌드하기

➜  wonderminah.github.io git:(master) ✗ rm -rf _site
➜  wonderminah.github.io git:(master) ✗ ll _site
➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll build
➜  wonderminah.github.io git:(master) ✗ ll _site
➜  wonderminah.github.io git:(master) ✗ bundle exec jekyll serve

해결되지 않았다.

두 파일은 빌드 후에도 로컬에서 존재하지 않았으나, 웹에서는 https://wonderminah.github.io/assets/css/main.css 가 문제없이 액세스 되었다. 웹에 빌드 시에는 어딘가에 파일이 로드되는 것인가 무엇인가… 몇 번 grep 을 해서 찾아보니, 로컬의 ./_sass/minimal-mistakes.scss 가 빌드시에는 /assets/css/main.css 에 만들어지는 것이 아닌가 싶었다. 설정의 문제로 컴파일이 제대로 안 된 것인지…

# head.html 에서 /assets/css/main.css 를 호출
./_includes/head.html:<link rel="stylesheet" href="/assets/css/main.css">

# https://wonderminah.github.io/assets/css/main.css 의 내용과 비슷한 것을 확인
./_sass/minimal-mistakes.scss: * Minimal Mistakes Jekyll Theme 4.24.0 by Michael Rose

Trouble Shooting 4 (미해결): 컴파일 대상에서 assets 폴더가 제외되어 있는지 확인하기

_config.yaml 의 exclude: 에 assets 폴더가 기재되어 있지는 않은지 확인해본다. 그런데, 그것도 아니었다.

# _config.yaml
exclude:

Trouble Shooting 5 (임시방편 해결)

근본 해결은 아닌것 같지만, 최후의 수단으로 그냥 웹에서 다운로드해서 디렉토리에 넣어버렸다.

➜  wonderminah.github.io git:(master) ✗ mkdir -p assets/css
➜  wonderminah.github.io git:(master) ✗ curl https://wonderminah.github.io/assets/css/main.css >> assets/css/main.css

➜  wonderminah.github.io git:(master) ✗ mkdir -p assets/js
➜  wonderminah.github.io git:(master) ✗ curl https://wonderminah.github.io/assets/js/main.min.js >> assets/js/main.min.js

우선은 다음 스텝을 나가기로 한다. 메모만 해두고 자잘한 개선은 나중에.