윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법입니다

Documentation Theme 특징

이 기술문서에 사용된 Documentation Theme의 가장 큰 특징은 다음과 같습니다.

- 문서를 카테고리별로 정렬해서 보여주는 네비게이션 리스트
- 문서 상단에 보여주는 문서 목차 (TOC)
- 다양한 상단 네비게이션 구성
- Tag를 활용해서 비슷한 주제의 문서를 함께 확인할 수 있음
도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법

설치 전체과정 요약

  1. Ruby 설치
  2. ridk 설치
  3. Documentation Theme 다운로드
  4. Jekyll gem 설치
  5. Bundler 설치

Ruby 설치

jekyll 최신 버전은 2022-03-03 현재 v.3.1이지만 여기서는 Documentation Theme를 기반으로 하기 때문에 호환이 잘되는 3.0을 설치합니다.

Ruby Installer 다운로드 경로 https://rubyinstaller.org/downloads/

위 사이트에서 rubyinstaller-devkit-3.0.3-1-x64 를 다운 받아 설치하면 됩니다.

윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법 - Ruby 다운로드

Ruby 설치 화면에서 PATH와 파일 확장자 연결에 체크 되어 있는지 확인하고 [Install] 버튼을 클릭합니다.

윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법 - Ruby 설치하기

설치할 컴포넌트 선택화면에서 모두 선택하거나 최소한 MSYS2 development toolchain은 꼭 선택하고 [Next] 버튼을 클릭합니다. 설치에 필요한 공간은 972MB 정도 됩니다.

윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법 - Ruby 설치하기

Ruby 설치가 끝나면서 완료화면에 Run ‘ridk install’ to setup MSYS2 and development toolchain. 이라는 옵션이 나타납니다. 꼭 설치해야 하는 툴이므로 반드시 선택하고 완료를 해서 바로 설치화면으로 이동하도록 합니다.

윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법 - Ruby 설치하기

ridk 설치

앞단계인 Ruby 설치 완료에서 ridk install을 선택했다면 ridk 설치 커맨드 창이 나타납니다.
(혹시 선택하지 않았다면 커맨드 창을 열어서 ridk install 을 입력하면 됩니다)
이때 설치 옵션을 선택할 수 있는데 Enter 키를 입력하면 기본 옵션인 1, 3으로 설치가 진행됩니다.

윈도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법 - ridk 설치하기

Documentation Theme 설치

Documentation Theme는 jekyll의 여러 테마 중에서 문서 작성에 특화된 테마입니다.

다운로드 경로

https://github.com/tomjoht/documentation-theme-jekyll

위 다운로드 경로에서 소스를 직접 다운 받거나 GitHub Desktop을 이용해서 가져오면 됩니다.

Live Demo

실제 Documentaion Theme를 적용하면 어떤 사이트를 만들 수 있는지 미리 확인해볼 수 있는 Live Demo 사이트가 있습니다.
https://idratherbewriting.com/documentation-theme-jekyll/

Jekyll gem 설치

우선 jekyll을 설치합니다.

gem install jekyll

Bundler 설치

  1. 다운로드 받은 Documentation theme 폴더를 오픈합니다.
  2. Gemfile 과 Gemfile.lock 파일을 삭제하거나 이름을 변경합니다.
  3. 다음 명령으로 bundler를 설치합니다: gem install bundler

  4. Bundler를 초기화 합니다: bundle init

    초기화 작업이 진행되면서 Gemfile 파일이 생성됩니다.

  5. Gemfile을 열어서 기존 내용을 삭제하고 다음 내용으로 변경합니다.

    source "https://rubygems.org"
  
gem 'jekyll', '~> 4.2.1'

group :jekyll_plugins do 
  gem 'jekyll-seo-tag', '~> 2.7.0'
  gem 'jekyll-sitemap', '~> 1.4.0'
  gem 'wdm', '~> 0.1.1'
  gem 'kramdown-parser-gfm'
end

gem "webrick", "~> 1.7"
  6. Gemfile을 저장합니다.
  7. 다음 명령어로 필요한 gem을 설치합니다: bundle install

사이트 실행, 접속

작업하면서 결과물을 확인할 때는 다음과 같은 명령어로 입력하고 브라우져에서 http://127.0.0.1:4000/ 로 접속하시면 되니다.

bundle exec jekyll serve

최종 결과 화면

위 절차대로 모두 실행하면 아래와 같은 화면을 볼 수 있습니다.

도 10 환경에서 Jekyll Documentation Theme를 설치하는 방법

사이트 빌드

작업이 끝난 결과물을 실제 서버나 gitHub에 업로드, 배포할 경우에는 다음 명령어로 빌드 한 후에 _site에 생성된 html 등을 사용하시면 됩니다.

bundle exec jekyll build

추가 패키지 설치

혹시 사이트 실행, 접속에서 오류가 발생하면 나타나는 메시지를 보고 처리를 해주면 됩니다.
혹시 필요한 gem이 설치되지 않았을 경우에는 다음과 같이 설치해주면 됩니다.

# gem 수동 설치 예시
gem install public_suffix -v 3.0.1
Tags: markdown jekyll windows