007. JeKyll 환경 - (3) 환경설정 기본값

환경 - (3) 환경설정 기본값

본 카테고리는 정적 블로그 생성도구인 Jekyll에 관하여 작성하는 곳이다.

공식 사이트의 내용을 좀 더 풀어쓰고 스크린샷을 첨부하여 좀 더 상세히 기록하고자 한다.

참고 Jekyll 공식 사이트

환경설정 기본값

아래는 Jekyll의 환경설정 옵션들의 기본값 목록이다.

기본적으로 Jekyll은 아래의 옵션값을 가진채로 실행된다.

이 환경설정 옵션의 값들은 command-line에서 입력하거나 _config.yml 파일에 명시적으로 저장하여 변경할 수 있다.

# 종류별 파일들의 위치
source:       .
destination:  ./_site
plugins_dir:  _plugins
layouts_dir:  _layouts
data_dir:     _data
includes_dir: _includes
collections:
  posts:
    output:   true

# 파일 읽기 취급
safe:         false
include:      [".htaccess"]
exclude:      ["Gemfile", "Gemfile.lock", node_modules", "vendor/bundle/", "vendor/cache/", "vendor/gems/", "vendor/ruby/"]
keep_files:   [".git", ".svn"]
encoding:     "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"

# 콘텐츠 필터링
show_drafts: null
limit_posts: 0
future:      false
unpublished: false

# 플러그인
whitelist: []
gems:      []

# 변환
markdown:    kramdown
highlighter: rouge
lsi:         false
excerpt_separator: "\n\n"
incremental: false

# 서버 동작(127.0.0.1:4000)
# serve 명령어를 참고하면 이해하기 쉽다
detach:  false
port:    4000
host:    127.0.0.1
baseurl: "" # does not include hostname
show_dir_listing: false

# 출력 방식
permalink:     date
paginate_path: /page:num
timezone:      null

quiet:    false
verbose:  false
defaults: []

liquid:
  error_mode: warn

# Markdown 처리
rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids:       true
  entity_output:  as_char
  toc_levels:     1..6
  smart_quotes:   lsquo,rsquo,ldquo,rdquo
  input:          GFM
  hard_wrap:      false
  footnote_nr:    1

주의 마크다운 처리의 kramdown은 두 가지 옵션을 지원하지 않는다
이는 kramdown의 HTML 변환기에 포함되지 않아서 생기는 현상으로 아래의 두 태그가 해당된다.
remove_block_html_tags
remove_span_html_tags

Liquid 옵션

• lax : 모든 오류를 무시한다.
• warn : 오류가 발생할 때마다 해당 오류를 콘솔에 출력한다.
• strict : 오류가 발생하면 오류 메시지를 출력 후 빌드를 중지한다.

Markdown 옵션

Jekyll이 지원하는 여러 Markdown 변환기에는 종종 추가 옵션을 가지고 있는 경우가 있다.

아래에서 Markdown 변환기중 대표적인 Redcarpet에 대해서 옵션값을 살펴보자.

Redcarpet

Redcarpet은 문자열 배열로 구성된 extentions라는 환경 설정을 제공한다.

redcarpet:
  extensions: []

이 배열에 들어가는 문자열은 각각 Redcarpet::Markdown 클래스의 확장자 중 하나의 이름이어야 하며, 배열 내 존재하는 확장자에 해당하는 기능의 값이 true로 설정된다.

Jekyll은 처리하는 특별한 두 가지의 Redcarpet extensions을 알아보자.

smart

smart를 적용하면 SmartyPants를 활성화한다.
따옴표를 인쇄용 따옴표로 변환하고 em을 (—)으로, en (-) 줄로 변환한다.

참고 원문에서는 곧은 따옴표와 곱슬 따옴표로 표현한다. 따옴표(‘ 또는 “)를 한컴오피스의 한글에 입력했을 때 약간 휘어있는 모양을 말한다.

위에서 언급한 no_fenced_code_blocks와 smart 이외에도 여러 확장기능들을 가지고 있다.

Jekyll의 Redcarpet은 3.2.x 버전을 사용하고 있으며 아래와 같은 확장 기능도 자주 사용된다.

tables

no_intra_emphasis

autolink

참고 Redcarpet의 사용가능한 extentions 목록

커스텀 Markdown 처리

만약 커스텀 Markdown 처리기에 관심이 있다면 Jekyll의 Markdown namespace에서 새로 클래스를 생성할 수 있다.

클래스의 경로는 아래 코드에 나와 있듯이 Jekyll::Converters::Markdown이다.

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

클래스를 생성하고 나면 _plugins 폴더의 플러그인으로 설정하거나 Gem으로 설정하여 _config.yml에 아래와 같이 저장한다.

markdown: MyCustomProcessor

증분 재생성(Incremental Regeneration)

일반적으로 알고 있는 증분빌드 와 유사하다.

증분 재생성은 이전 빌드와 비교하여 업데이트 된 문서와 페이지만 다시 생성하여 빌드시간을 단축한다.

증분 재생성은 .jekyll-metadata 에서 파일을 Tracking하며
Tracking 대상은 파일 수정 시간과 문서간 종속성 등을 포함한다.

현재 증분 재생성은 document나 page 중 하나를 수정하거나 해당하는 document와 page의 종속성을 수정한 경우에만 동작한다.

종속성은 include태그를 쓰는 inlcudes와 Layout만 Tracking되며 다른 문서에 대한 참조는 종속성으로 Tracking하지 않는다. (Ex : post 목록을 출력하기 위해 site.post를 반복하는 것)

종속성이 완벽히 Tracking되지 않는 단점을 해결하기 위한 방법으로 document의 front-matter에 regenerate : true를 넣으면 무조건 증분 재생성 대상에 포함된다.
하지만 front-matter에 지정한 문서만 재생성하며 참조하는 document를 재생성되지 않는다.

증분 재생성을 활성화 하려면 옵션으로 --incremental 또는 -I 플래그를 사용하거나 _config.yml 파일에서

incremental : true

위와 같이 설정하여 활성화 할 수 있다.

주의 증분 재생성은 실험적인 기능이다.
일반적이지 않은 모든 시나리오에서 올바르게 작동함을 보장할 수 없다.
따라서 신중하게 사용해야 하며 Issue가 발생할 시 Github에서 문제를 등록하면 된다.

참고 Jekyll 관련 Issue 등록 링크