번역 / 교정

2.x 에서 3.x 로 업그레이드

Jekyll 을 업그레이드 하려고요? 먼저, Jekyll 3 에서 바뀐 점을 몇 가지 알아두어야 합니다.

변경내용을 살펴보기 전에, 먼저 Jekyll 을 최신 버전으로 업그레이드 하세요:

gem update jekyll

버전 3.2 부터, Jekyll 은 루비 버전 2.1 또는 그 이상을 필요로 합니다.

뛰어들기

당장 Jekyll 사이트를 만들어보고 싶다고요? 그냥 jekyll new 사이트이름 을 실행하기만 하면 Jekyll 사이트의 골격이 담긴 새 디렉토리가 만들어집니다.

site.collections 변화

버전 2.x 에서는, site.collections 을 사용하여 첫 번째 아이템으로 컬렉션 레이블, 두 번째 아이템으로 컬렉션 객체를 가진 배열을 얻을 수 있었습니다. 버전 3.x 에서는, 이런 복잡함을 제거하여 단순하게 컬렉션 객체를 얻을 수 있습니다. 따라서, 템플릿에 약간의 수정이 필요합니다:

  • collection[0] 은 collection.label 로
  • collection[1] 은 collection 으로

site.collections 를 사용할 때, 위와 같이 수정했는지 확인 바랍니다.

For site.collections.myCollection in Jekyll 2, you now do:

{% assign myCollection = site.collections | where: "label", "myCollection" | first %}

처음엔 번거롭게 느껴질 수 있으나, 거대한 for 루프와 비교하면 더 간단합니다.

Textile 지원

Textile 을 더 이상 기본으로 지원하지 않으므로, Textile 파일을 사용하려면 이제부터는 jekyll-textile-converter 를 설치해야 합니다.

일부 의존요소 제거

Core Team 이 판단하기에 필수가 아닌 여러 의존요소들을 제거했습니다. 따라서 이 기능들을 사용중이었다면, v3.0 에서는 별도로 직접 설치해야 합니다. 그 기능들은 다음과 같습니다:

  • jekyll-paginate – 과거 버전에 있었던 Jekyll 페이지 나누기 기능
  • jekyll-coffeescript – CoffeeScript 처리
  • jekyll-gist – gist Liquid 태그
  • pygments.rb – Pygments 강조 기능
  • redcarpet – 마크다운 처리기
  • toml – 환경설정 YAML 을 대체하는 기능
  • classifier-reborn – site.related_posts 기능

미리 작성한 게시물

2.x 에서는 --future 플래그가 자동적으로 _활성화_되어 있던 문제가 있었습니다. future 플래그는 포스트 작성자가 현재 이후의 시간을 포스트에 할당하여 해당 시점에 도달하기 전까지 포스트가 게시되지 않도록 해주는 기능입니다. Jekyll 3 에서는 이 기능을 수정하였습니다. 지금부터, --future 는 비활성화되어 있는 것이 디폴트입니다. 따라서, jekyll build 나 jekyll serve 를 실행할 때 미리 작성한 포스트가 생성되게 하려면 --future 를 사용해야 합니다.

GitHub Pages 에서 미리 작성한 게시물

GitHub Pages 사이트들은 예외로, 기록의 일관성 유지 차원에서 --future 플래그가 기본적으로 활성화 되어 있습니다.

레이아웃 메타데이터

layout 을 소개합니다. Jekyll 2 와 그 이전 버전에서는, 레이아웃의 모든 메타데이터가 Liquid 변수인 page 에 들어가 있었습니다. 이는 데이터 통합에 많은 혼란과 의도치 않은 결과를 일으켰습니다. Jekyll 3 에서 레이아웃 데이터에 접근하기 위한 Liquid 변수는 layout 입니다. 예를 들어, 레이아웃의 머리말에 class: my-layout 이 있다면, 레이아웃에서는 {{ layout.class }} 로 이 값을 사용할 수 있습니다.

구문 강조기 변경

highlight 태그와 백틱 문자 코드 블록에 대한 디폴트 구문 강조기가 처음으로 바뀌었습니다. 이제부터는, Pygments.rb 대신 Rouge 를 사용합니다. highlight 태그에 사용하던 몇몇 옵션, 예를 들면 hl_lines, 들은 Rouge 에서 작동하지 않을 수도 있습니다. 계속해서 Pygments 를 사용하고자 한다면, _config.yml 파일에 highlighter: pygments 를 설정한 후에, gem install pygments.rb 를 실행하거나 프로젝트의 Gemfile 에 gem 'pygments.rb' 를 추가하세요.

상대적 고유주소 기능 제거

Jekyll 3 부터, 상대적 고유주소는 사용을 권장하지 않는 기능으로 결정되었습니다. 당신의 사이트가 Jekyll 2 또는 그 이하의 버전에서 생성되었다면, serve 또는 build 시 다음과 같은 에러가 발생할 수 있습니다:

Since v3.0, permalinks for pages in subfolders must be relative to the site
source directory, not the parent directory. Check
https://jekyllrb.com/docs/upgrading/ for more info.

당신의 _config.yml 아리에서 다음 내용을 제거하면 이 에러는 해결됩니다:

relative_permalinks: true

더 이상 고유주소의 끝에 슬래시가 붙지 않습니다

Jekyll 2 에서, permalink: 로 생성된 모든 URL 에는 끝부분에 자동으로 슬래시(/)가 추가되었었습니다. Jekyll 3 는 permalink: URL 의 끝에 더 이상 슬래시를 자동으로 추가하지 않습니다. 이로인해 페이지를 가리키는 예전 링크들은 404 에러를 발생할 가능성이 있습니다. 예를 들어, 여기 페이지가 하나 있다고 가정해봅시다. 이 페이지에는 YAML 로 permalink: /:year-:month-:day-:title 이 있어서 URL 은 example.com/2016-02-01-test/ (끝에 슬래시가 있음) 가 되며, Jekyll 은 내부적으로 2016-02-01-test 라는 이름의 폴더를 생성하게 됩니다. Jekyll 3 에서는, 동일한 permalink: 설정이 2016-02-01-test.html 이라는 파일을 생성하며 그 URL 은 example.com/2016-02-01-test 가 되고, 결과적으로 예전 URL 들은 모두 404 에러를 발생하게 됩니다. 이 문제점을 피해 동일한 URL 을 유지하기 위해서는, permalink: 의 끝에 슬래시를 추가해야만 합니다. 예시, permalink: /:year-:month-:day-:title/.

내 게시물이 모두 사라졌어요! 어디 간거야!

당신의 _config.yml 파일에 future: true 를 추가해보세요. 이제 게시물이 보이나요? 만약 보인다면, 당신은 루비의 시간 처리방식에 관련된 이슈에 걸려들었던 것입니다. 당신의 게시물들은 당신이 의도한 것과 다른 타임존으로 처리되어, 컴퓨터의 현재 시간과 비교해서, “미리 작성한” 게시물로 인식됩니다. 이 문제를 해결하는 방법은 모든 게시물에 타임존 오프셋을 추가(하고 _config.yml 파일에서 future: true 를 제거하는 것입니다). 예를 들어, 당신이 지금 있는 곳이 캘리포니아라면:

---
date: 2016-02-06 19:32:10
---

를 아래와 같이 변경해야 합니다 (오프셋 주목):

---
date: 2016-02-06 19:32:10 -0800
---

카테고리가 작동하지 않아요!

만약 카테고리가 /_posts/code/2008-12-24-closures.md 처럼 구성되어 있다면, 카테고리를 _posts 디렉토리 위로 옮겨서 디렉토리 구조를 다시 정리해야 합니다. 예시, /code/_posts/2008-12-24-closures.md.