[RESOLVED] GitHub(깃허브) 블로그(페이지) 지킬(Jekyll) 빌드 오류 이슈 [해결책 포함]

이 문제는 최신 버전의 릴리스로 해결 되었습니다.

문제점과 원인

오늘 TIGER 미국배당다우존스 ETF의 수익률 분석 글을 작성했습니다. 티스토리 대신 GitHub 블로그로 글을 올리려고 했는데, 느닷없이 오류가 발생했습니다.

에러 메시지는 다음과 같습니다.

/usr/local/bundle/gems/jekyll-3.9.4/lib/jekyll/excerpt.rb:135:in `extract_excerpt': undefined method `excerpt_separator' for #<Jekyll::Page:0x000055f05b1c22e8> (NoMethodError)

이에 대해 동일한 문제가 발생한 분이 이슈로 등록해 놓았습니다.

원인은 github-pages가 228에서 229로 업그레이드 되면서, 지킬도 3.9.3에서 3.9.4 버전을 사용하게 되었는데, 이 3.9.4 버전에 문제가 있거나 github-pages 229와 충돌이 나는 듯 합니다.

최종 해결책

Workflow 중에 GitHub Pages Jekyll이 있습니다. GitHub에서 페이지를 빌드하는 pages-build-deployment와 동일한 것입니다. 다만 리포트를 생성하는 단계인 pages-build-deployment가 없을 뿐입니다.

이 Workflow를 가져오되 그 안에 있는 actions/jekyll-build-pages만 이전 버전으로 바꾸면 됩니다.

        uses: actions/jekyll-build-pages@v1

        uses: actions/jekyll-build-pages@v1.0.9

버그 이슈에도 이 해결책을 간단하게 설명해서 올려 두었으니 참고하기 바랍니다.

임시 해결책 2가지

임시 해결책은 2가지를 제시되고 있습니다.

1. 로컬에서 빌드해서 올린다.
2. 기본 pages-build-deployment action 대신 GitHub Action을 정의해서 사용한다.

어느 방법이든 사용할 github-pages 버전은 229 이전 버전인 228로 설정해야 합니다. Gemfile에 아래와 같이github-pages 버전을 지정해야 합니다.

gem "github-pages", "=228"

커스텀 action은 사용해 보지 않았는데, 문제가 단기간에 해결되지 않을 듯 하면, (해당 이슈는 이틀 전에 등록되었습니다) 두 번째 방법을 사용해 보려고 합니다.

GitHub Action을 이용한 임시 해결 방법

GitHub Action을 정의하면 일시 해결이 가능합니다.

1. [리포지토리] > Actions > New workflow를 선택합니다.
2. jekyll로 검색하여 Jekyll이라고 되어 있는 workflow를 찾습니다.
3. 해당 workflow의 Configure 버튼을 누릅니다.
4. Commit changes 버튼을 눌러, 본인 workflow로 등록합니다.
5. 로컬 지포지토리에서 git pull 명령으로 workflow 등록 commit과 싱크를 맞춥니다.
6. 로컬 리포지토리에서 git push 명령으로 푸시합니다.

이렇게 설정하면 푸시할 때 본래 있던 pages-build-deployment workflow와 새로 만든 Deploy Jekyll site to Pages workflow 둘 다 실행됩니다. 제대로 동작하지 않는 pages-build-deploymnet workflow는 중지시켜 놓아도 되고, 해결될 때를 빠르게 파악하기 위해 켜두어도 됩니다.

참고로 Jekyll workflow는 최신 버전에 가까운 지킬 4.3.3을 실행합니다.

Fetching jekyll 4.3.3
Installing jekyll 4.3.3

기존 버전인 3.9.3을 사용하고 싶은 경우에는 Gemfile에 다음과 같은 설정을 추가하면 됩니다.

gem "jekyll", "=3.9.3"

Fetching jekyll 3.9.3
Installing jekyll 3.9.3

하지만 이 경우 workflow에 정의된 다른 플러그인들과 버전이 맞지 않아 추가적인 설정이 필요할 듯 합니다.

Dependency Error: Yikes! It looks like you don't have kramdown-parser-gfm or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- kramdown-parser-gfm' If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/! 

추가 (2024년 2월 11일)

Jekyll workflow가 기본 pages-build-deployment workflow와 동일한 기능을 제공하는 줄 알았는데 아니었습니다.

Jekyll workflow는 최신 버전 지킬을 GitHub 상에서 돌릴 수 있게 하는 것이 목적이지, 기존 pages-build-deployment를 대체할 목적으로 개발한 것이 아닌 듯 합니다.

pages-build-deployment workflow는 여러 환경 변수를 설정해서 Jekyll을 부릅니다.build 아래 Build with Jekyll 단계를 보면, 상당히 많이 설정해서 넘깁니다.

/usr/bin/docker run --name ghcrioactionsjekyllbuildpagesv1010_7e857f --label 3db9e4 --workdir /github/workspace --rm -e "INPUT_SOURCE" -e "INPUT_DESTINATION" -e "INPUT_FUTURE" -e "INPUT_BUILD_REVISION" -e "INPUT_VERBOSE" -e "INPUT_TOKEN" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" ...

이 중에 일부는 GitHub용으로 지킬을 사용할 때 (또는 플러그인이) 참조하는 환경 변수입니다.

제 경우에는 site.url을 사용해서 테스트 사이트인지 아니면 운영 사이트인지 구분하고, 여기에 맞춰 일부 기능은 다르게 동작하도록 설정해 두었습니다. 구글 애널리틱스 설정도 조건부로 동작시키는 기능 중에 하나인데, 하루 정도 트래픽이 없어 원인을 파악해보니 환경 변수가 제대로 넘어가지 않고 있었습니다.

_config.yml의 url 변수가 site.url인데, 따로 설정하지 않으면, 넘어온 환경 변수의 값을 참조하여 자동 생성합니다. 그러니 Jekyll workflow를 그냥 돌리게 되면 site.url은 아무런 값이 없게 됩니다.

사용하는 테마나 설정한 기능에 따라 다르겠지만, site.url이 제대로 설정되어 있어야 동작하는 기능이 있을 수 있습니다. Minimal Mistakes의 경우 repostiry 변수를 코멘트 기능에 사용하고 있으니, 이런 부분이 제대로 동작하지 않는 분은 확인해 보시기 바랍니다.

관련 링크

• [[Bug]: Error: undefined method `excerpt_separator' for #[Jekyll::Page #9544]
• pages build and deployment - New Jekyll Update #1878