깃허브 블로그를 만들기로 결심하면서, 어떻게 만들어야하는지 여러가지 방법을 찾아봤는데 최근 글이 아닌 1년 이상된 글이 많아 헷갈리는 부분도 있었고, 시행착오도 있었다. 그래서 Mac M2 20250310 기준 내가 깃허브 블로그를 개설하기까지의 시행착오와 방법을 담았다.
1. 깃허브 블로그 레포지토리 개설
먼저, 깃허브 블로그를 만들기 위해서는 새로운 레포지토리를 생성해야하는데, 아래와 같은 형식으로 생성하면 된다.
- Repository name을 username.github.io 형식으로 입력(username은 자신의 GitHub 사용자명).
- 레포지토리를 Public으로 설정
- Add a README file 체크
- 'Create repository'를 클릭하여 레포지토리 생성
2. 로컬로 Clone 하기
레포지토리를 만들었다면 내 PC로 클론해오는 작업을 하면 된다. 디렉토리를 하나 만든 후, 해당 경로에 접속하여 clone 받는다.
git clone https://github.com/username/username.github.io.git
cd username.github.io
3. Jekyll 테마 고르기 및 내 프로젝트에 적용하기
깃허브 블로그를 생성할 때, 보통 Jekyll 테마를 많이 이용하는데 너무 잘 되어있다. 원하는 테마를 골라 블로그에 적용하면 된다. 나는 이 중에서 깔끔하게 정리된 Chirpy 테마를 선택했고, 버전은 7.2.4 버전이다. 여기까지는 어렵지 않다.
- Chirpy 테마 GitHub 저장소로 이동
- 'Code' 버튼을 클릭하고 'Download ZIP' 선택
- 다운로드한 ZIP 파일을 풀고, 압축 푼 파일 모두를 앞서 clone한 로컬 레포지토리 복사
4. Ruby 설치
내 프로젝트에 잘 복사해왔다면 그 다음으로 Ruby를 설치해야한다. Jekyll은 Ruby로 작성되어있어 Ruby 개발 환경 설정이 필요하다. homebrew가 설치되어있다는 가정하에 진행하므로, homebrew가 설치되어있지 않다면 homebrew 먼저 설치해줘야한다.
brew install rubyRuby를 설치한후, 이제 프로젝트 경로에서 파일 의존성을 설치해줘야한다.
bundle install잘 설치되다가 여기서 첫번째 에러를 만났다.
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Could not find compatible versions
..........생략
Because every version of jekyll-theme-chirpy depends on Ruby ~> 3.1
and Gemfile depends on jekyll-theme-chirpy >= 0,
Ruby ~> 3.1 is required.
So, because current Ruby version is = 2.7.6,
version solving has failed.에러 내용은 Ruby 3.1 이상을 필요로하는데 현재 시스템에는 Ruby 2.7.6이 설치되어있어서 발생하는 문제였다. 그래서 Ruby 버전을 업그레이드 시켜준 후, 버전을 재확인해보는데 3.1 버전을 설치했지만 여전히 2.7.6에서 바뀌지 않는 문제가 있었다.
brew install ruby@3.1
ruby -v # 버전 확인 (3.1 이상인지 확인)
brew install ruby@3.1
Warning: ruby@3.1 3.1.6 is already installed and up-to-date.
To reinstall 3.1.6, run:
brew reinstall ruby@3.1
ruby -v
ruby 2.7.6p219 (2022-04-12 revision c9c2245c0a) [arm64-darwin22]ruby의 경로를 확인하여 쉘프로필에 추가해주는 작업까지 진행하여, 해당 에러는 해결이 되었다.
# 다음 명령으로 Ruby 3.1의 설치 경로 확인
brew info ruby@3.1
/opt/homebrew/opt/ruby@3.1/bin
/opt/homebrew/lib/ruby/gems/3.1.0/binecho 'export PATH="/opt/homebrew/opt/ruby@3.1/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcecho 'export PATH="/opt/homebrew/lib/ruby/gems/3.1.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc5. 다시 의존성 설치
Ruby 버전 오류를 해결하고, 다시 의존성 설치를 시도했는데 두번 에러를 만났다.
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Installing eventmachine 1.2.7 with native extensions
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.
An error occurred while installing eventmachine (1.2.7), and Bundler
cannot continue.
In Gemfile:
jekyll-theme-chirpy was resolved to 7.2.4, which depends on
jekyll-archives was resolved to 2.3.0, which depends on
jekyll was resolved to 4.4.1, which depends on
em-websocket was resolved to 0.5.3, which depends on
eventmachine이 오류에 대해서 찾아보니 eventmachine gem을 설치하는 과정에서 네이티브 확장(native extension)을 빌드하지 못해 발생하는 문제로, 주로 컴파일러나 빌드 도구가 없거나 잘못 설정되어 있을 때 발생한다고 한다. 로그에 대해서 좀 더 자세히 보기 위해 아래 명령어를 입력한 후, 추가 로그를 확인해보니 eventmachine 설치 과정에서 C++ 컴파일러가 iostream 헤더 파일을 찾지 못해 실패하고 있다는 에러였다. C++ 개발 도구가 제대로 설정되지 않았기 때문인 것 같았다.
# 오류 로그 더 자세히 보기
bundle install --verbose그래서 클로드와 함께 해당 에러를 해결할 수 있는 방법을 찾아나갔다. 먼저 Xcode Command Line Tools 설치를 확인했는데 이미 설치되어있다고 나와 패스.
xcode-select --install두번째로 C++ 컴파일러 환경변수를 설정해주었다.
export CPLUS_INCLUDE_PATH=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1
export LIBRARY_PATH=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib
export C_INCLUDE_PATH=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include그리고 C++ 컴파일러 환경을 직접 지정하여 eventmachine을 설치해주었고,
gem install eventmachine -v '1.2.7' -- --with-cppflags="-I$(xcrun --show-sdk-path)/usr/include/c++/v1"다시 번들 설치를 시도했다. C++ 컴파일러 관련 에러가 나온 이유는 Jekyll 자체는 Ruby로 작성된 정적 사이트 생성기이지만, 일부 Ruby gem들은 성능을 위해 C나 C++로 작성된 네이티브 확장을 포함하고 있어 발생할 수 있다고 한다.
bundle install번들 설치 시도 후, 다시 한번 실패! 이유는 시스템 Ruby 경로에 권한이 없어서였다.
eventmachine -- --with-cppflags="-I/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1"
Ignoring ffi-1.15.5 because its extensions are not built. Try: gem pristine ffi --version 1.15.5
Fetching eventmachine-1.2.7.gem
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.마지막으로 Homebrew Ruby 사용 설정을 해준다.
# Ruby 3.1 경로 확인
which ruby
# 만약 /opt/homebrew/opt/ruby@3.1/bin/ruby가 표시되지 않는다면:
# 현재 세션에서만 PATH 설정
export PATH="/opt/homebrew/opt/ruby@3.1/bin:$PATH"
# gem 경로도 설정
export GEM_HOME="$HOME/.gem"
export PATH="$HOME/.gem/bin:$PATH"
# 이제 gem install 명령 다시 시도
gem install eventmachine -- --with-cppflags="-I$(xcrun --show-sdk-path)/usr/include/c++/v1"경로가 제대로 설정되었는지도 확인!
which ruby # /opt/homebrew/opt/ruby@3.1/bin/ruby 가 나와야 함
ruby -v # 3.1.x 버전이 나와야 함
which gem # Homebrew Ruby의 gem을 가리켜야 함최종적으로 bundle install이 성공했고, 아래 명령어를 입력해 로컬에 바로 띄워봤다. 성공.
bundle exec jekyll serve
로컬에 띄우는 것까지는 성공했으나, Chirpy 내부 config 파일 세팅부터 실제 깃허브 페이지에 연동하는 것까지 아직 과정이 남아있다. 두가지 모두 어렵지 않으니, 이어서 작성할 예정이다.
