Jekyll에서 Just the Docs 테마 적용하기

Jekyll에서 Just the Docs 테마 적용하기

이 포스팅은 Jekyll 사이트에 Just the Docs 테마를 적용하는 방법을 단계별로 정리합니다. 이 작업은 GitHub 계정이 필요하며, Docker와 Docker-compose가 설치된 WSL2(Ubuntu 22.04) 환경에서 테스트 하였습니다.

---

Just the Docs 테마 fork 하기

1. 테마 fork

먼저, Just the Docs의 GitHub 페이지로 이동하여 'Fork' 버튼을 클릭해 자신의 GitHub 계정으로 테마를 복제합니다.

2. 테마 동작 확인

위와 같이 GitHub에서 fork한 후, Setting > General 에서 Repository name 을 아래와 같은 형식으로 변경합니다.

Setting > General 에서 Repository name 변경

그리고, 브라우저를 사용해서 변경한 Repository name 으로 접속이 잘 되는지 확인 합니다.

Repository name 으로 접속이 잘 되는지 확인

저의 경우는 해당 테마의 GitHub 리포지토리에서 최신 변경사항(upstream)을 적용받지 않기로 결정했습니다. 이유는 최근 커밋들에서 gem을 통한 일부 패키지 설치 과정에서 에러가 발생했기 때문입니다. 물론 이 문제는 테마의 자체 문제가 아니고, 관련된 종속적인 패키지 간의 버전 문제일 가능성이 높습니다. 이러한 문제를 피하기 위해, 안정적인 이전 버전인 v0.5.4 태그를 사용하였습니다.

Docker를 로컬에서 통해 동작시키기

1. 로컬에서 git clone 하기

본인의 저장소에 fork 된 소스를 클론 합니다. 그리고 이전 버전인 v0.5.4 태그로 reset 하고 강제로 commit 합니다. (협업 저장소일 경우에는 매우 유의해서 사용해야함)

$ git clone (본인의 테마 사본)
$ git reset --hard 9959191af18956ce1764e7823f2fc9dc0cc5edd5
$ git push push  -f origin main

2. docker build 하기

테마에는 이미 Dockerfile 이 포함되어 있습니다. 아래와 같은 명령어로 docker 를 build 합니다.

$ docker build -t docker-jekyll .
[+] Building 13.9s (8/8) FINISHED
...
> [4/4] RUN gem install bundler && bundle install:
12.19 ERROR:  Error installing bundler:
12.19   The last version of bundler (>= 0) to support your Ruby & RubyGems was 2.4.22.
Try installing it with `gem install bundler -v 2.4.22`
12.19   bundler requires Ruby version >= 3.0.0. The current ruby version is 2.7.8.225.
------
Dockerfile:10
--------------------
   8 |
   9 |     COPY Gemfile just-the-docs.gemspec ./
  10 | >>> RUN gem install bundler && bundle install
  11 |
  12 |     EXPOSE 4000
--------------------
ERROR: failed to solve: process "/bin/sh -c gem install bundler && bundle install" did not complete successfully: exit code: 1

Docker 빌드 시 발생하는 에러를 해결하기 위해 Dockerfile을 아래와 같이 수정합니다.

$ git diff Dockerfile
diff --git a/Dockerfile b/Dockerfile
index a499513..0e5d844 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,6 +7,7 @@ ENV LANGUAGE en_US.UTF-8
 WORKDIR /usr/src/app

 COPY Gemfile just-the-docs.gemspec ./
-RUN gem install bundler && bundle install
+RUN gem install bundler -v 2.4.22
+RUN bundle install

 EXPOSE 4000

Dockerfile을 수정한 후, docker build 를 통해 docker image 를 생성 합니다.

2. docker image 실행 하기

Docker-compose를 사용하여 로컬 환경에서 테스트합니다. 설정이 완료되면, 다음 커맨드를 사용하여 Jekyll 서비스를 시작합니다.

docker-compose up -d

Docker 컨테이너가 실행되면, 웹 브라우저를 사용하여 localhost:4000 주소로 이동합니다. 이 주소는 로컬 컴퓨터에서 실행 중인 Jekyll 사이트에 접근하는 데 사용됩니다. 브라우저에서 이 주소를 입력하면, Just the Docs 테마가 적용된 Jekyll 사이트의 홈페이지가 표시됩니다.

이 페이지에서는 사이트의 레이아웃, 색상, 폰트 등 테마의 모든 요소를 확인할 수 있습니다. 또한, 로컬에서 사이트의 변경사항을 실시간으로 확인하고, 필요한 경우 즉시 수정할 수 있습니다. 이 과정을 통해, Just the Docs 테마를 적용한 Jekyll 사이트를 로컬 환경에서 효과적으로 테스트하고, 실시간으로 변경사항을 확인할 수 있습니다.