Jekyll <small>with</small> Jekyll Bootstrap

Jekyll은 루비 기반에서 돌아가는 parsing engine 이다. github.io계정 위에서 간단히 블로그를 운영하고 싶을 때 사용할 수 있다.

github.io 페이지 사용법 : 공식 도움말, 번역 블로그
Jekyll Documentation Page : http://jekyllrb.com/docs/home/
Jekyll Bootstrap Quick Start : http://jekyllbootstrap.com/usage/jekyll-quick-start.html

Install

Jekyll은 ruby 기반이므로 먼저 ruby와 gem이 설치되어 있어야 한다.

$ gem install jekyll

Jekyll Bootstrap

Jykyll Bootstrap 은 Jekyll을 블로그로 사용할 수 있도록 기본적인 파일들과 디렉토리들의 부트스트랩을 제공하는 툴이다.
http://jekyllbootstrap.com/ 에 접속해서 github id 를 입력하면 부트스트랩 git repository를 클론할 수 있는 명령어를 출력해준다.

$ git clone https://github.com/plusjade/jekyll-bootstrap.git neocjmix.github.com
$ cd neocjmix.github.com
$ git remote set-url origin git@github.com:neocjmix/neocjmix.github.com.git
$ git push origin master

Bootstrap을 설치했으면, 바로 서버를 띄워서 preview 해볼 수 있다.

Setting

_config.yml파일을 통해 기본적인 세팅을 할 수 있다. 이 파일은 YAML 문법으로 되어 있다.
세팅 파일을 변경한 후에는 preview 시 서버를 종료했다가 다시 시작해야만 적용된다.

Adding & editing Pages

_가 붙어있지 않는 디렉토리 내의 파일들은 파싱되어 서버에 올라간다. 이 파일들은 해당 경로대로 서버에서 접근 가능하며, html이나 md 파일들은 pages 목록에 등록된다.

따라서 기본적으로 마련된 페이지 이외에도, 임의의 경로로 자유롭게 페이지를 등록하는 것이 가능하다.

index.md , index.html : 블로그 첫 페이지를 장식하는 페이지이다. 디폴트로 설정되어 있는 파일을 잘 살펴보면 반복문등을 참조하여 블로그 포스팅 리스트를 만들 수도 있다.
categories.html, pages.html, archive.html,… : 이 파일들을 살펴보면 jekyll bootstrap include 파일들을 이용해서 각 유형의 페이지들을 리스팅 하는것을 알 수 있다.

페이지 소스 맨 처음에는 일련의 설정을 해줄 수 있다. 다음은 주요 설정의 예이다.

---
layout: page //_layouts 디렉토리의 템플릿중 사용할 것을 정한다. (post, page,..)
group: navigation //사이트 상단의 내비게이션에 해당 페이지의 링크를 출력한다.
title : Posts // 제목
category: "ETC"
tags: [blog, Jekyll, markdown]
---

Posting

아래와 같이 입력하면 새로운 포스팅을 작성할 수 있다. 새 포스팅은 _post 디렉토리에 markdown 파일로 생성된다.

$ rake post title="title" [date="yyyy-mm-dd"] [category="category"]

해당 파일을 수정하거나 삭제하면 블로그에도 동일하게 반영된다.

Template engine

Liquid 템플릿 엔진을 사용한다.
다음 형식을 통해서 syntax highlighting 을 할 수 있다.

입력

{% highlight javascript %}
function $initHighlight(block, flags) {
  try {
    if (block.className.search(/\bno\-highlight\b/) != -1)
      return processBlock(block, true, 0x0F) + ' class=""';
  } catch (e) {
    /* handle exception */
  }
  for (var i = 0 / 2; i < classes.length; i++) { // "0 / 2" should not be parsed as regexp
    if (checkCondition(classes[i]) === undefined)
      return /\d+/g;
  }
}
{% endhighlight %}

결과

function $initHighlight(block, flags) {
  try {
    if (block.className.search(/\bno\-highlight\b/) != -1)
      return processBlock(block, true, 0x0F) + ' class=""';
  } catch (e) {
    /* handle exception */
  }
  for (var i = 0 / 2; i < classes.length; i++) { // "0 / 2" should not be parsed as regexp
    if (checkCondition(classes[i]) === undefined)
      return /\d+/g;
  }
}

Preview

아래와 같은 명령어로 테스트용 서버를 4000 포트에 띄울 수 있다.

$ rake preview

로컬서버를 띄운 후에 post나 theme, config 파일등, 관련있는 local 파일을 변경하면 http://localhost:4000에 바로 반영된다.

Publishing

github계정 에remote 연결을 해두었기때문에 preview를 하고 만족스럽다면 다음과 같이 commit & push 하면 된다.

$ git commit -m "Jekyll with Jekyll Bootstrap"
$ git push

실제 github.io 서버에 수 분 안에 반영이 완료된다.

Comments

DISQUS는 자체 서버 없이도 운영 가능한 댓글 기능을 제공하는 서비스로 Jekyll Bootstrap은 이를 통한 댓글 기능을 지원한다.

https://disqus.com/websites/ 에서 관련 기능을 지원하고 있으며, 워드프레스 등 각종 블로그 툴에도 쉽게 적용 가능한 플러그인을 제공하고 있다.

이외에도 Facebook 댓글등 몇몇 댓글 서비스를 지원한다.

_config.yml 파일에서 다음 부분 설정을 통해 사용할 수 있다. 초기에는 Jekyll Bootstrap 계정으로 셋팅되어있으므로 수정해주어야 한다.

# Settings for comments helper
# Set 'provider' to the comment provider you want to use.
# Set 'provider' to false to turn commenting off globally.
#
comments :
  provider : disqus
  disqus :
    short_name : jekyllbootstrap
  livefyre :
    site_id : 123
  intensedebate :
    account : 123abc
  facebook :
    appid : 123
    num_posts: 5
    width: 580
    colorscheme: light

directories

감춰지는 디렉토리 - ‘_‘가 붙은 디렉토리는 기본적인 작동에 사용된다.
- _posts : 블로그 포스트들
- _drafts : 날짜 없는 포스트 ( 숨겨진 포스트 )
- _inludes : 인클루드 되는 내용. theme 도 여기에 포함된다.
  - JB : Jekyll Bootstrap 에서 사용하는 파일들
  - theme : 테마 파일
- _layouts : 각 파일 상단에 layout이 설정되면 여기의 파일을 베이스로 렌더링한다.
- _plugins : 플러그인 디렉토리
- _site : 최종 convert 되어 서버에 올라가는 파일. 만약 서버에 내용이 업데이트가 잘 되지 않거나 이상이 있으면 이 디렉토리를 삭제하고 재시작 하면 해결된다.
서버에 보여지는 디렉토리 - 이 디렉토리는 서버에 output 된다.
- assets : 주로 theme에서 사용하는 asset 들이 들어있다.
- pages : 페이지 내용은 그대로 해당 경로로 파싱되어 올라간다.

Using Themes

테마 사용법이 설명된 링크 : http://jekyllbootstrap.com/usage/jekyll-theming.html

Install

git 저장소를 이용해 테마를 설치할 수 있다.

$ rake theme:install git="https://github.com/jekyllbootstrap/theme-the-program.git"

Switch

아래 명령어를 사용하면 _layout 폴더 내의 세 파일 내의 인클루드 경로가 변경되며 테마를 적용하게 된다.

$ rake theme:switch name="the-program"

Customizing

테마는 기본적으로 _layout 폴더 내의 세 파일들에 인클루드된 내용을 따라 적용된다. 해당 내용을 살펴보면 _includes/themes 디렉토리의 해당 테마 내부의 파일들로 연결되어 있다. 또 이 파일들은 페이지나 포스트를 파싱해서 처리할 때 사용될 뿐 서버에 노출되지 않으므로 css 등 esset 파일들은 외부에 있는 essets 디렉토리 안에 위치해서 링크시키게 된다. 따라서 essets 에 있는 css 파일을 수정하는것 만으로도 스타일을 변경시킬 수 있다.

테마 작성시 참고할 수 있는 API 레퍼런스 : http://jekyllbootstrap.com/api/theme-api.html#toc_5

이 외에도 기본으로 제공되는 파일 중 index 파일이나 categories 파일 등의 소스를 잘 살피면 기본적인 루프 문법이나 데이터 구조에 대한 힌트를 손쉽게 얻을 수 있다.

또 _includes/JB 디렉토리 내부의 파일을 살펴보면 여러 문법에 대한 설명이 코멘트 처리 되어 있으므로 참고할 수 있다.

포스팅을 모두 출력하는 루프의 예

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{% for post in site.posts %}
    <article>
      <header>
        <ul class="categories">
          {% for category in post.categories %}
          <li><a href="{{ BASE_PATH }}{{ site.JB.categories_path }}#{{ category }}-ref">{{ category }}</a></li>
          {% endfor %}
        </ul>
        <h1><a href="{{ BASE_PATH }}{{ post.url }}">{{ post.title }}</a></h1>
        <span class="date">{{ post.date | date_to_string }}</span>
      </header>
      <section class="excerpt">
        {{ post.excerpt }}
      </section>
      <section class="tags">
        <h2>tags</h2>
        <ul>
          {% for tag in post.tags %}
            <li><a href="{{ BASE_PATH }}{{ site.JB.tags_path }}#{{ tag }}-ref">{{ tag }}</a></li>
          {% endfor %}
        </ul>
      </section>
    </article>
{% endfor %}