Jekyll + GitHub Pages 트러블슈팅

warning: It seems your ruby installation is missing psych

$ gem install jekyll
/Users/ooxo/.rbenv/versions/3.0.0/lib/ruby/3.0.0/yaml.rb:3: warning: It seems your ruby installation is missing psych (for YAML output).
To eliminate this warning, please install libyaml and reinstall your ruby.
## 후략

ruby를 새로 설치해서 해결했습니다.

$ rbenv uninstall 3.0.1
$ rbenv install 2.7.3

error: use of undeclared identifier ‘rb_thread_select’; did you mean ‘rb_thread_fd_select’?

$ gem install jekyll 
Building native extensions. This could take a while...
ERROR:  Error installing jekyll:
        ERROR: Failed to build gem native extension.
    current directory: /Users/ooxo/.rbenv/versions/2.7.3/lib/ruby/gems/2.7.0/gems/eventmachine-1.2.7/ext
## 중략
em.cpp:706:13: error: use of undeclared identifier 'rb_thread_select'; did you mean 'rb_thread_fd_select'?
        if ((ret = rb_thread_select(kqfd + 1, &fdreads, NULL, NULL, &tv)) < 1) {
## 후략

rbenv부터 새로 설치해서 해결했습니다.

먼저 ruby와 rbenv를 삭제합니다.

$ gem env  
RubyGems Environment:
  - RUBYGEMS VERSION: 3.1.6
  - RUBY VERSION: 2.7.3 (2021-04-05 patchlevel 183) [arm64-darwin20]
## 중략
  - SHELL PATH:
     - /Users/ooxo/.rbenv/versions/2.7.3/bin
     - /opt/homebrew/Cellar/rbenv/1.1.2/libexec
     - /Users/ooxo/.gem/ruby/2.7.0/bin
     - /Users/ooxo/.rbenv/shims
     ## 후략

$ which gem
/Users/ooxo/.rbenv/shims/gem

$ rbenv uninstall 2.7.3
$ brew uninstall rbenv

$ which gem
/usr/bin/gem

이후 아래 디렉토리도 삭제해 주었습니다.

/Users/ooxo/.rbenv
/Users/ooxo/.gem

환경변수 $PATH도 수정해 주었습니다.

$ echo $PATH
/Users/ooxo/.gem/ruby/2.7.0/bin: ## <- 이 부분을 찾아서 삭제 했습니다.
## 후략

마지막으로 다시 rbenv, ruby를 설치하여 해결했습니다.

$ brew install rbenv
## rbenv 설치 이후, 설명대로 쉘 환경에 RUBY_CONFIGURE_OPTS를 추가해줍시다.

$ rbenv install 3.0.1

$ rbenv init
## 설명대로 쉘 환경에 eval "$(rbenv init -)"를 추가해줍시다.

WARNING: You don’t have /Users/…/bin in your PATH, gem executables will not run.

$ gem install --user-install bundler jekyll
Fetching bundler-2.2.17.gem
WARNING:  You don't have /Users/ooxo/.local/share/gem/ruby/3.0.0/bin in your PATH,
	  gem executables will not run.
## 후략

환경변수 $PATH에 RubyGems 경로를 넣어서 해결했습니다. (참고)

PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin:$PATH"

Bundler could not find compatible versions for gem “jekyll”

$ jekyll -v
Resolving dependencies...
/Users/ooxo/.local/share/gem/ruby/3.0.0/gems/bundler-2.2.17/lib/bundler/resolver.rb:68:in `rescue in start': Bundler could not find compatible versions for gem "jekyll": (Bundler::VersionConflict)
## 중략
- `jekyll (~> 3.8) arm64-darwin-20` required by `beautiful-jekyll-theme (5.0.0) (arm64-darwin-20)`
## 후략

버젼 충돌을 일으키는 Gem을 Gemfile에서 찾아 삭제하여 해결했습니다.

You have already activated ffi 1.15.1, but your Gemfile requires ffi 1.15.0.

$ jekyll -v
/Users/ooxo/.local/share/gem/ruby/3.0.0/gems/bundler-2.2.17/lib/bundler/runtime.rb:302:in `check_for_activated_spec!': You have already activated ffi 1.15.1, but your Gemfile requires ffi 1.15.0. Prepending `bundle exec` to your command may solve this. (Gem::LoadError)
## 후략

에러 메세지의 도움말처럼 bundle exec를 사용하여 해결했습니다.

Jekyll의 Quickstart 페이지도 이를 권장하고 있습니다.

$ bundle exec jekyll -v
jekyll 4.2.0

혹은 bundle update를 사용하여 해결했습니다. (참고)

$ bundle update
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
## 중략
Bundle updated!

$ jekyll -v
jekyll 4.2.0

cannot load such file – webrick (LoadError)

$ bundle exec jekyll serve
Configuration file: /Users/ooxo/code/eungook.github.io/_config.yml
## 중략
/Users/ooxo/.local/share/gem/ruby/3.0.0/gems/jekyll-4.2.0/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError)

webrick을 Gemfile에 추가하여 해결했습니다.

$ bundle add webrick
Fetching gem metadata from https://rubygems.org/..........
## 중략
Using webrick 1.7.0
## 후략

$ bundle exec jekyll serve
## 정상 동작을 확인할 수 있습니다.

404 Page not found :( The requested page could not be found.

포스트 목록에는 뜨지만, 포스트 상세는 404 Page Not found가 뜹니다.

포스트 목록과 포스트 상세의 페이지 주소를 확인해주세요.

제 경우는.. 포스트 목록의 주소는 http://localhost:4000/ 로컬이었고,
포스트 상세의 페이지 주소는 https://eungook.github.io/2021/05/19/1.html 이었습니다.

Jekyll 테마에 따라 포스트 상세의 주소가 상대경로로 되어 있기도 하고, _config.yml의 url을 참고한 절대경로로 되어 있기도 합니다.

Page build failure

GitHub Pages의 주소로 접속이 안 되고, 아래와 같이 빌드 실패의 메일이 옵니다.

The page build failed for the gh-pages branch with the following error:

No /docs folder was found to build GitHub Pages. Check the source setting for this repository. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#missing-docs-folder. (후략)

깃헙 리파지터리 설정을 확인해주세요.

Settings> Pages> Source에서 브랜치와 폴더 설정을 다시 확인해줍시다.
제 경우는 브랜치는 gh-pages, 폴더는 /(root)로 설정하여 해결했습니다.

Google Analytics will only appear in production

Jekyll의 기본 테마인 minima의 Google Analytics는 development 환경에서는 동작하지 않도록 되어 있습니다. 쉘의 환경변수를 JEKYLL_ENV=production 이렇게 설정하기를 권하는데요, 번거롭습니다. 하여

$ (export JEKYLL_ENV=production; jekyll serve)

이렇게 인라인으로 환경변수를 부여합시다.