이전 글 Hexo: icarus 테마 git기반 설치와 업그레이드 에 변경과 configurationsfile 을 더한 내용이다.

static file 기반 블로엔진인 Hexo에서 테마로 icarus 를 사용하려고 한다. 여기서는 icarus theme를 git으로 설치한다. 그리고 최신 버전으로 업그레이드 하는 과정을 살펴본다. 또한 icarus theme의 구성 파일에 대해서 좀 더 세부적으로 살펴본다.

1. Icarus theme git 설치
2. Configuration files
3. Upgrade

1. Icarus theme git 설치

icarus 테마는 getting-started-with-icarus 에 설명이 되어 있다. 여기서는 git 을 클론해서 사용해 보도록 하겠다.

- git clone

icarus 릴리즈 페이지 https://github.com/ppoffice/hexo-theme-icarus/releases 를 확인해서 원하는 버전 번호를 찾는다. hexo 프로젝트 폴더에 들어가서 아래 같이 5.0.0 버전을 지정해서 클론을 수행한다.

1
2

$ cd PROJECT_FOLDER
$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b 5.0.0 --depth 1

클론한 결과는 아래 같은 폴더 구조를 갖는다.

1
2
3
4
5
6

themes/icarus
    ├── include
    ├── languages
    ├── layout
    ├── scripts
    └── source

- 설정

이제 hexo의 구성 파일 _config.yml 에 테마를 icarus 로 지정한다.

1
2

#_config.yml
theme: icarus

그리고 icarus 구성 파일 _config.icarus.yml 에 먼저 버전을 명시하고 icarus 테마 관련 설정을 진행한다.

1

version: 5.0.0

Configuration files

Icarus theme의 구성파일은, jyekyll 의 구성요소 + icarus 구성 파일로 제공한다. 구성 파일을 통해서 여러 형식의 화면 표현을 가능하게 한다. _config.yml 와 같은 위치에 있으면 된다.

아래는 구성파일의 우선순위 순서로 작성되어 있다:

• _config.yml: 사이트 구성 파일 (jekyll 의 기본 구성파일)
  • hexo _config.yml
• _config.icarus.yml: Icarus theme 기본 구성파일.
• 레이아웃 구성 파일
  • _config.post.yml : 글 내용 POST 레이아웃 화면/위젯 구성
  • _config.page.yml : 페이지의 레이아웃 화면/위젯 구성
• Jykell 의 Post/page front-matter
• (Deprecated) Legacy theme configuration file at themes/icarus/_config.yml
• (Deprecated) Legacy layout configuration file at themes/icarus/_config.post.yml and themes/icarus/_config.page.yml

Layout Configuration Files

레이아웃 구성은 icarus theme 의 구성파일과 같은 구조를 갖는다. 모든 블로그 포스트의 레이아웃을 위해서 _config.post.yml 파일을 참조한다. 그리고 _config.page.yml 은 사용자 지정 페이지를 위한 레이아웃에 적용된다.

_config.icarus.yml 파일:

• 세 개의 컬럼으로 사이트의 레이아웃을 배치한다.

  1 2 3 4 5 6 7 8 9 10

  widgets: - type: recent_posts position: left - type: categories position: right - type: tags position: right

_config.post.yml 파일

• POST는 위젯 위치를 left 로 두어서 위젯+본문의 두개 컬럼으로 구성된다.

1
2
3
4
5
6
7
8
9
10

widgets:
    -
        type: recent_posts
        position: left
    -
        type: categories
        position: left
    -
        type: tags
        position: left

Post/Page Front-matter

어떤 페이지/포스트에서 사이트/레이아웃 구성을 오버라이드 하려면 해당 포스트(글) 혹은 페이지의 Front-matter 로 구성해 사용하면 된다.

작성한 포스트 source/_post/some-post.md 에 선언한 Front-matter 구성.

1
2
3
4
5
6
7
8

title: My first post
date: '2015-01-01 00:00:01'
article:
    highlight:
        theme: atom-one-dark
---
# Some Post

some-post.md 의 Front-matter 는 아래 사항을 오버라이드한다.

• _config.post.yml, _config.icarus.yml 의 article.highlight 를 atom-one-dark 로 재구성한다.
• 단, font-matter에서 title, date, updated, comments, layout, source, photos, and excerpt 등은 재정의 되지 않는다.

Site Configuration File

앞서 설명한 icarus 테마, 레이아웃, font matter 파일을 사이트 구성파일을 재정의 한 것이다.

3. Upgrade

다른 버전의 icarus theme 로 업그레이드를 하려면 기존 폴더를 백업해 두고 다시 git clone을 통해 다운로드하고 _config.icarus.yml 구성 파일에 버전과 내용을 변경해서 사용하면 된다.

예를 들어 앞서 5.0.0 버전을 백업하고 5.1.1 버전으로 업그레이드 한다면 아래 같이 기존 irarus 를 icarus_5.0.0 같이 백업해 두고 새 버전이 잘 적응되는지 확인후 정리하면 된다.

1
2

$ cd PROJECT_FOLDER/theme
$ mv icarus icarus_5.0.0

이어서 새 버전을 git clone 한다.

1

$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b 5.1.1 --depth 1

hexo의 구성 파일 _config.icarus.yml 에 새 icarus 테마 버전을 명시한다.

1

version: 5.1.1

hexo 서버를 재시작해 정상적으로 동작하는지 확인한다. 그런데 필요한 npm 모듈 업그레이들 요구한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

$ hexo server
INFO  Validating config
Inferno is in development mode.
INFO  =======================================
 ██╗ ██████╗ █████╗ ██████╗ ██╗   ██╗███████╗
 ██║██╔════╝██╔══██╗██╔══██╗██║   ██║██╔════╝
 ██║██║     ███████║██████╔╝██║   ██║███████╗
 ██║██║     ██╔══██║██╔══██╗██║   ██║╚════██║
 ██║╚██████╗██║  ██║██║  ██║╚██████╔╝███████║
 ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝
=============================================

ERROR Package hexo-component-inferno's version (1.1.0) does not satisfy the required version (^2.0.2).
ERROR Please install the missing dependencies your Hexo site root directory:
ERROR npm install --save hexo-component-inferno@^2.0.2
ERROR or:
ERROR yarn add hexo-component-inferno@^2.0.2

요구에 따라 업그레이드 해주면 된다.

1

$ npm install --save hexo-component-inferno@^2.0.2

정상적으로 업그레이드 되어서 server가 실행되는 것을 확인할 수 있다. 단, hexo clean 이후 에러를 만날 수 있어 보인다.

업그레이드 후 db.json 에러 대응

clean 해서 새로 생성하기 위해서 clean 명령후 generate 를 2번 정도 실행하면 보통는 db.json 에러가 없어지는데 업그레이드 후 아래 같이 계속 발생한다.

1
2
3

INFO  === Registering Hexo extensions ===
FATAL Error: [hexo-include-markdown] Could not open db.json .
    at ReadFileContext.callback (/Users/qkboo/work-blog/thinkbee.github.io/node_modules/hexo-include-markdown/lib/orverwriteCache.js:22:15)

블로그 solved-hexo-include-markdown 를 따라 다음 같이 처리했다.

1
2
3
4

#
$ npm install hexo-include-markdown --save
# clean & generate
$ hexo clean;echo "{}" > db.json;hexo generate

Upgrade to Icarus 5.2.1

2023/7월 Icarus 5.2.1 로 업그레이드 진행

1

git clone https://github.com/ppoffice/hexo-theme-icarus.git icarus -b 5.2.1

_config.icarus.yml 에 icarus theme 버전을 명시한다.

1

version: 5.2.1

서버를 재시작하고 확인한다. npm 모듈등… 문제가 없이 잘 진행된다.

참고

1. User guide: configurations

이 글은 github pages 를 통해서 블로그를 할 수 있도록 다음 작업을 한다:

• 로컬에 ruby를 기반으로한 jekyll 을 설치한다.
• github pages 와 연동한다.
• markdown 으로 작성한 문서를 github pages 에 올린다.

jekyll

jekyllrb.com 의 가이드에 따라 github page에서 블로그로 사용하고자 한다.

설치

Ruby 개발 도구가 반드시 필요 - 여기서 macOS 에서 블로그 작업을 한다고 가정한다.

• macOS는 Ruby 최신 버전이 제공되고 있다.
• 여기선 Homebrew 로 루비를 설치하고 사용한다.

jekyll에서 Bootstrap 4 사용하기

bootstrap4 는 2017-6월 현재 alpha 버전으로 jekyll 과 github page에 적용하기 위해서 몇가지 구성과 설정을 해주어야 한다.

bootstrap 4 gem 추가

bootstrap4는 sass를 지원하고, 실제 sass 파일을 추가하거나 gem으로 설치하는 두 가지 방법으로 설치한다.

• (1) sass 소스 파일 추가
• (2) Gem 으로 설치

만약 bootstrap 3를 사용한다면 Bootstrap 3은 Less로 작성되었고, Jekyll은 Sass를 지원한다.[^3]

여기서는 Bootstrap Ruby gem 으로 설치한다

bootstrap gem을 설치하고 설정을 한 후에 github page에서 사용하기 위해 마지막 섹션에 설명한 것 처럼 bootstrap scss 파일을 복사하는 과정을 거친다.

Gemfiles

Gemfile 파일을 열고 bootstrap, autoprefixer-rails, jekyll-assets gem을 추가한다. [^2]. 또한 Gemfile 에서 minima 테마 gem을 막는다.

1
2
3
4
5
6
7

# gem "minima", "~> 2.0"

group :jekyll_plugins do
    gem "jekyll-feed", "~> 0.6"
    gem 'bootstrap', '~> 4.0.0.alpha4'
    gem 'autoprefixer-rails'
    gem 'jekyll-assets'

• autoprefixer-rails: Autoprefixer for Ruby and Ruby on Rails
• jekyll-assets: Jekyll을 위한 Sprockets 3 사용한 Asset pipelines.

_config.yml

_config.yml 을 열고, minima 사용을 막는다.

1
2
3
4
5
6

#theme: minima
gems:
  - jekyll-feed
  - bootstrap
  - autoprefixer-rails
  - jekyll-assets

새로 추가한 bootstrap gem을 bundle 명령으로 설치한다.

1

$ bundle install

assets/main.scss

assets/main.scss 파일에 minima를 사용하지 않고, bootstrap에서 사용할 scss 파일을_sass/ 폴더에 작성한다.

1
2
3
4
5

//@import "minima";
@import "bootstrap";
@import "_custom"; // before 'main', variables for bootstrap
@import "main";
@import "blog";

• @import “bootstrap” 은 bootstrap gem을 통해 scss 소스를 읽어 온다.

여기서는 _custom.scss 파일은 bootstraps 변수, blog.scss 파일은 블로그 테마를 구성하도록 추가해서 구성했다.

_sass/custom.sass 파일

이 파일은 bootstrap4 scss _variables 에 있는 변수를 다시 정의한다. 다음 같다 [^2]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Bootstrap overrides

// Options
$enable-flex:               true;
$enable-rounded:            false;
$enable-shadows:            false;
$enable-gradients:          false;
$enable-transitions:        true;

// Typography
@font-face {
    font-family: "NotoSansCJKkr-Regular";
    src: url( '../assets/fonts/NotoSansCJKkr-Regular.otf') format( 'opentype');
}
@font-face {
    font-family: "NotoSansCJKkr-Bold";
    src: url( '../assets/fonts/NotoSansCJKkr-Bold.otf') format( 'opentype');
    font-style: bold;
}
@font-face {
    font-family: "NotoSansCJKkr-Light";
    src: url( '../assets/fonts/NotoSansCJKkr-Light.otf') format( 'opentype');
}

$base-font-family: "NotoSansCJKkr-Regular", "Helvetica Neue", Arial, sans-serif !default;

$font-family-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
$font-family-base:       $font-family-sans-serif;

_sass/main.scss 파일

여기서 main.scss 에서는 TAG에 대한 전체적인 구성을 했다. minima 에서 가져온 코드등이 혼재한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

/*
 * Globals
 */
@media (min-width: 48em) {
  html {
    font-size: 18px;
  }
}

@mixin media-query($device) {
  @media screen and (max-width: $device) {
    @content;
  }
}

@mixin relative-font-size($ratio) {
  font-size: $font-size-base * $ratio;
}


// Width of the content area
$on-palm:          600px !default;
$on-laptop:        800px !default;

$background-color: #fdfdfd !default;

$spacing-unit:     30px !default;
$footer-height: 4.5rem;

$small-font-size:  $font-size-base * 0.875 !default;
$base-line-height: 1.5 !default;

$my-body-font: "NotoSansCJKkr-Regular", "Helvetica Neue", Arial, sans-serif !default;


/*
 * TAG
 */
html {
  position: relative;
  min-height: 100%;
}

body {
  font: $font-weight-base #{$font-size-base}/#{$base-line-height} $my-body-font;
  color: #111;
  background-color: $background-color;
}

h1, .h1,
h2, .h2,
h3, .h3,
h4, .h4,
h5, .h5,
h6, .h6 {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
  font-weight: normal;
  color: #333;
}


table, td, th {
    border: 1px solid #003300;
}
table {
    border-collapse: collapse;
    border-spacing: 0;
}

th {
    border: 2px solid black;
}

td {
    padding: 1px 2px;
}

/*
 * Syntaxhighliting from minima
 */
%vertical-rhythm {
  margin-bottom: $spacing-unit / 2;
}

// Import partials from minima
@import
  "minima/syntax-highlighting"
;

마지막엔 아직 다른 syntaxhighter를 설치 안하고 기존 minima에서 사용하던 syntaxhighliter 를 사용하게 했다.

layout 파일

• the post
• page layouts

_include/head.html 파일

1
2
3
4
5

<link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}">
<link
  rel="stylesheet"
  href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css"
/>

_layout/default.html 파일

footer.html 구문 밑에 bootstrap 관련 스크립을 추가한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{% include header.html %}

<div class="container-fluid">
  <div class="row">{{ content }}</div>
</div>

{% include footer.html %}

<!-- JavaScript -->
<script
  src="https://code.jquery.com/jquery-3.1.1.slim.min.js"
  integrity="sha384-A7FZj7v+d/sdmMqp/nOQwliLvUsJfDHW+k9Omg/a/EheAdgtzNs3hpfag6Ed950n"
  crossorigin="anonymous"
></script>
<script
  src="https://cdnjs.cloudflare.com/ajax/libs/tether/1.4.0/js/tether.min.js"
  integrity="sha384-DztdAPBWPRXSA/3eYEEUWrWCy7G5KFbe8fFjk5JAIxUYHKkDx6Qin1DkWx51bBrb"
  crossorigin="anonymous"
></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/js/bootstrap.min.js"></script>

header.html

header.html 을 bootstrap navbar 형태로 다음 같이 변경한다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<nav class="navbar navbar-toggleable-sm navbar-inverse bg-inverse bg-faded fixed-top">

    {% assign default_paths = site.pages | map: "path" %}
    {% assign page_paths = site.header_pages | default: default_paths %}

    <button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse"
        data-target="#nav-content" aria-controls="nav-content" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon"></span>
    </button>

    <a class="navbar-brand" href="{{ "/" | relative_url }}">{{ site.title | escape }}</a>

    {% if page_paths %}
    <div class="collapse navbar-collapse justify-content-end" id="nav-content">
        <ul class="navbar-nav">
            {% for my_page in site.pages %}
            {% if my_page.title %}
            <li class="nav-item">
              <a class="nav-link" href="{{ my_page.url | prepend: full_base_url }}">{{ my_page.title | escape }}</a>
            </li>
            {% endif %}
            {% endfor %}
        </ul>
    </div>

    {% endif %}
</nav>

navbar에서 참조한 구현 사례는 여기 샘플을 참조한다.

footer.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<footer class="footer">

    <h3>{{ site.title | escape }}</h3>

    <div class="row">
      <div class="col-md-3 footer-col">
        <ul class="contact-list">
          <li>
            {% if site.author %}
              {{ site.author | escape }}
            {% else %}
              {{ site.title | escape }}
            {% endif %}
            </li>
            {% if site.email %}
            {% comment %}<li><a href="mailto:{{ site.email }}">{{ // site.email }}</a></li>{% endcomment %}
            {% endif %}
        </ul>
      </div>

      <div class="col-md-3 footer-col">
        <ul class="social-media-list">
          {% if site.github_username %}
          <li>
            {% include icon-github.html username=site.github_username %}
          </li>
          {% endif %}

          {% if site.twitter_username %}
          <li>
            {% include icon-twitter.html username=site.twitter_username %}
          </li>
          {% endif %}
        </ul>
      </div>

      <div class="col-md-5 footer-col">
        <p>{{ site.description | escape }}</p>
      </div>
    </div>

</footer>

{% if page.comments %}
  <!-- Disqus comment count -->
  <script id="dsq-count-scr" src="//{{ site.disqus.shortname }}.disqus.com/count.js" async></script>
{% endif %}

1
2

<div class="container-fluid">
  <div class="row">

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<div class="container-fluid">
  <div class="row">

    <h1 class="page-heading">Posts</h1>

    {{ content }}

    <ul class="post-list">
      {% for post in site.posts %}
        <li>
          {% assign date_format = site.minima.date_format | default: "%b %-d, %Y" %}
          <span class="post-meta">{{ post.date | date: date_format }}</span>

          <h2>
            <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title | escape }}</a>
          </h2>
        </li>
      {% endfor %}
    </ul>

    <p class="rss-subscribe">subscribe <a href="{{ "/feed.xml" | relative_url }}">via RSS</a></p>

  </div>
</div>

bootstrap gem과 github pages

github page에 올리기 위해서 gem 설치한 bootstrap themem 파일이 필요하다. 로컬에서는 bootstrap gem 으로 bootstrap의 scss 소스를 사용하지만 github page에서는 실제 scss 파일이 함께 저장소에 있어야 한다.

먼저 다음 같이 bootstrap gem 위치로 이동한다.

1
2

$ cd `bundle show bootstrap`
/usr/local/lib/ruby/gems/2.4.0/gems/bootstrap-4.0.0.alpha6 $

스타일 시트 파일을 로컬 _scss 폴더 밑으로 복사한다.

1
2

$ cd assets/stylesheets
$ cp -r * ~/work-blog/qkboo-github-work/_sass/

Gemfile, _config.yml

bootstrap gem 사용을 막는다.

mamima 테마 삭제

minima 테마를 사용하지 않으므로 관련 파일이 있으면 삭제한다.

deleted:    _sass/minima.scss
deleted:    _sass/minima/_base.scss
deleted:    _sass/minima/_layout.scss

단, _sass/minima/_syntax-highlighting.scss 는 일단 유지하자.

github page update 문제

jekyll 등에서 작업한 내용을 push 했지만 github page 내용이 변경되지 않는 경우, scss 파일 등에 에러가 있을 수 있다. 해당 페이지 프로젝트의 Settings -> Github pages 섹션에 에러가 표시된다.

github page error

참조

[^1]: Bootstrap for Sass
[^2]: Bootstrap 4 + Jekyll
[^3]: Using Bootstrap CSS with Jekyll

jekyll 기본 사용

• 지킬 사이트의 테마 이용
• 전역 설정
• 글쓰기
• 사이트 변환

New site

new 명령을 jekyll의 gem-based themes 를 사용하게 구성해 준다.
혹은 빈 폴더에서 새롭게 구성할 수 있다.

jekyll new

jekyll new로 생성되는 사이트는 gem-based theme를 사용한 jekyll project bootstrapped 로 생성된다.

jekyll new SITE_NAME 으로 생성

1

$ jekyll new myblog

아래 같은 템플릿 파일로 구성되다.

1
2
3
4
5
6
7

Gemfile
Gemfile.lock
_config.yml
_posts/
_site/
about.md
index.md

중요한 구성 파일은,

빈 사이트 만들기

1

$ jekyll new myblog --blank

디렉토리 구조만 생성된다.

1
2
3
4

_draft/
_layout/
_posts/
index.html

_config.yml

• jekyll configuration 참조
• jekyll 설정 참조

1
2
3
4

markdown: kramdown
highlighter: pygments
permalink: pretty
relative_permalinks: false

Jekyll 실행 환경을 지정할 수 있다. 예를 들어 디버깅, 개발, 운영 환경으로 구분한다면 코드에 다음 같이 넣을 수 있다:

1
2
3

{% if jekyll.environment == "production" %}
  {% include disqus_comments.html %}
{% endif %}

jekyll을 실행시 JEKYLL_ENV에 값을 지정해 줄 수 있다. 기본 값은 development 이다.

1
2

$ JEKYLL_ENV=production bundle exec jekyll build
$ JEKYLL_ENV=production jekyll build

지킬의 포스트 등에서 사용하는 변수는 https://jekyllrb.com/docs/variables/ 에서 확인할 수 있다.

github 지원 config items

아래는 GitHub에서 기본으로 제공하는 설정으로 사용자가 원하는 대로 변경이 가능한 설정.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

github: [metadata]
kramdown:
  input: GFM
  hard_wrap: false
gems:
  - jekyll-coffeescript
  - jekyll-paginate

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false

• lsi : 관련 포스트글에 대한 인덱스를 생성.
• safe : 사용자 플러그인을 비활성화 하고, 심볼릭 링크(symbolic links)를 무시.
• source : Jekyll이 읽을 파일의 위치를 변경.
• incremental : 수정 변경한 포스트만 다시 빌드하는 옵션.
• highlighter : rough highlighter 지정
• gist : GitHub gist 사용 설정.

post

포스트는 _posts 폴더에 저장한다. yyyy-mm-dd-파일명.markup( md 또는 markdown 또는 textile) 형식으로 포스트 파일명을 만들어야 한다.

파일 내용은 다음 같이 구성된다.

Front matter
BODY

Front matter 는 다음 같이 구성되고, Front Matter, **머리말**를 참조한다.

YAML 머리말 블록을 가진 모든 파일을 특별한 파일로 인식하여 처리하고, 머리말은 반드시 올바른 YAML 형식으로 작성되어야 하며, 대시문자 3개(—)로 감싸서 파일의 맨 첫 부분과 끝 부분에 위치한다.

BODY 내용은 마크다운, 기타 문법 형식으로 작성하면 된다.

[]다른 포맷 지원](http://jekyllrb-ko.github.io/docs/plugins/#converters-1)

Front Matter 머릿말

세 개의 대쉬 라인(—) 사이에 메타 정보를 넣는다.

1
2
3
4
5
6

---
layout: post
title: "Welcome to Jekyll!"
date: 2017-05-03 18:53:47 +0900
categories: jekyll update
---

• 빈 메타 정보는 빈 두개의 — 로 둔다.

Front matter 에 사용할 수 있는 내장된 변수는 다음 같다:

외부 자원

이미지, 다운로드 파일 등을 사용할 때는 루트 디렉토리의 images, assets, downloads 라는 디렉토리를 만들고 그곳에 둔다. 그리고 해당 자원의 참조를 / 경로를 기준으로 삼으면 된다.

1

![친절한 스크린샷](/screenshot.jpg)

site.url 변수

1

![친절한 스크린샷]({{ site.url }}/assets/screenshot.jpg)

1

… PDF 를 직접 [다운로드]({{ site.url }}/assets/mydoc.pdf)할 수 있습니다.

Build

실제 웹 사이트에는 html 파일로 제공되야 한다. 그러기 위해서 serve 혹은 build 명령으로 마크다운 파일을 변환해야 한다.

jekyll serve 명령은 지킬 사이트 디렉터리 안으로 접근하여 실행해야 한다.

serve 명령으로 빌드한 html과 파일은 _site 폴더에 생성된다.

Jekyll은 기본 테마로 Minima라 불리는 gem-based theme를 사용한다. 이 테마를 구성하는 파일은 jekyll new 명령으로 위치에 다음 같이 구성된다.

Minima 테마는 assets, _layouts, _includes, and _sass 디렉토리를 실제 Minima theme gem 디렉토리에 위치하고 있고 아래 같은 구성으로 사이트가 생성된다.

1
2
3
4
5
6
7

├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2016-12-04-welcome-to-jekyll.markdown
├── about.md
└── index.md

다른 Theme gem을 사용하려면 bundle update를 실행하거나 bundle update <THEME> 로 사용할 를 지정한다.

jekyll은 사이트 접근시 처음에 컨텐츠를 아래 폴더 안에서 찾는다.

• /assets
• /_layouts
• /_includes
• /_sass

예를 들어 post 레이아웃을 사용하고 있다면 _layouts 폴더에 _layouts/page.html 테마 파일을 생성해 변경할 수 있다. 처음부터 생성하는 것 보다 기본 테마 파일을 이용하는 것이 빠르다.

Minima 테마의 기본 폴더는 bundle show minima 명령으로 확인이 가능하다. 기본테마 디렉토리는 아래 같이 구성되어 있다. 테마 정의에 필요한 _includes/, _layouts/, _sass/, assets/ 폴더이다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

├── _includes
│   ├── disqus_comments.html
│   ├── footer.html
│   ├── google-analytics.html
│   ├── head.html
│   ├── header.html
│   ├── icon-github.html
│   ├── icon-github.svg
│   ├── icon-twitter.html
│   └── icon-twitter.svg
├── _layouts
│   ├── default.html
│   ├── home.html
│   ├── page.html
│   └── post.html
├── _sass
│   ├── minima
│   │   ├── _base.scss
│   │   ├── _layout.scss
│   │   └── _syntax-highlighting.scss
│   └── minima.scss
└── assets
└── main.scss

기본 테마 재정의 하기

Jekyll theme는 기본 layouts, includes, stylesheets를 지정하는데, 이것을 사이트 콘텐트에 맞게 재정의할 수 있다.

Minima 테마의 기본 폴더는 bundle show minima 명령으로 확인이 가능하다. 그리고 아래 같이 찾아서 열어 볼 수 있다. 먼저 macOS 는

1

open $(bundle show minima)

Windows 에서는

1

explorer /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0

기본 테마 디렉토리 구조를 복사해 와서 작업하겠다.

1
2

$ cd `bundle show minima`
~minima-2.1.1$ cp -r _includes _layouts _sass assets ~/mysite/

각각의 테마 요소를 알아보자.

Layout

컨텐츠의 구성은 _layouts 폴더에 넣는다. 이렇게 구성해 보자

1
2
3

default.html|
            ├<-- post.html
            ├<-- page.html

_sass 디렉토리에 .sass 파일을 두면 sass 컴파일러가 컴파일 한다.

fonts

외부 폰트, ttf, otf 등의 폰트를 _assets/fonts 같은 폴더에 다운로드하고 css로 불러와 사용한다.

그리고 _sass/main.scss 등의 css 파일에 다음 같이 폰트를 선언한다.

1
2
3
4
5
6
7
8
9

@font-face {
  font-family: "NotoSansCJKkr-Regular";
  src: url("../_assets/fonts/NotoSansCJKkr-Regular.otf") format("opentype");
}
@font-face {
  font-family: "NotoSansCJKkr-Bold";
  src: url("../_assets/fonts/NotoSansCJKkr-Bold.otf") format("opentype");
  font-style: bold;
}

그리고 html 혹은 css 에서 font-family 이름을 사용하면 된다.

1
2
3
4

h1,
h2 {
  font-family: "NotoSansCJKkr-Bold";
}

disqus.com 에서 새 사이트를 구성하고, Jekyll 을 선택하면 Universal code 를 얻을 수 있다.

1. comments 변수

comments 변수를 YAML Front Matter에 추가하기 위해, Jekyll의 manima 테마에서 _layouts/post.html 에 변수를 추가해 준다.

1
2
3
4

---
layout: default
comments: true
---

2. Universal code

댓글 수 표시

1
2
3
4
5

{% if page.comments %}
  <!-- Disqus comment count -->
  <script id="dsq-count-scr" src="//{{ site.disqus.shortname }}.disqus.com/count.js" async></script>
{% endif %}

href 속성에 #disqus_thread 를 추가하기 위해서, _layouts/post.html 템플릿에 다음을 추가한다.

1
2
3
4
5
6

{% if page.author %}
• <span itemprop="author" itemscope itemtype="http://schema.org/Person"><span itemprop="name">{{ page.author }}</span></span>
{% endif %}
{% if page.comments %}
  • <a href="{{ site.url }}{{ page.url }}#disqus_thread">Comments</a>
{% endif %}

이제 제목 밑에 disqus 링크가 표시된다.

{:width=”400”}

조건에 page.conmments 를 참조하면 post 에 comments: true 가 정의되면 되고, layout 전체를 담당하려면 아래 같은 layout.comments 를 비교한다:

1
2
3

{% if layout.comments %}
  • <a href="{{ site.url }}{{ page.url }}#disqus_thread">Comments</a>
{% endif %}

jekyll new 로 새 사이트를 설치하면 __includes/google-analytics.html 이 포함되어 있다. Google Analytics에서 Tracking ID를 발급받아 사용하면 된다.

Google account가 있으면 손쉽게 만들수 있다.여기 에서 로그인해서 Admin > Property > Tracking Info > Tracking Code 에서 찾을 수 있다.

Tracking ID

파일 __includes/google-analytics.html 안의 {{ site.google_analytics }}에 Tracking ID가 치환 되는데, 이것은 _config.yml 파일 google_analytics: 항목에 본인의 Tracking ID를 입력한다.

1
2

# Google services
google_analytics: UA—XXXXXXXX-X

이 파일을 _includes/head.html 파일에는 production 모드에서 analytics가 적용이 된다.

1
2
3

{% if jekyll.environment == 'production' and site.google_analytics %}
{% include google-analytics.html %}
{% endif %}

운영모드인 production 은 github 에 업로드시 자동으로 적용된다. 만약 다른 사이트에 업로드하려면 빌드를 한다.
$ JEKYLL_ENV=production bundle exec jekyll build

Pagenation

지킬에서 jekyll-paginate gem 을 추가하면 페이지 구분을 추가할 수 있다.

https://jekyllrb.com/docs/pagination/

Gemfile과 _config.yml

Gemfile에 추가.

1
2
3

group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.6"
   gem "jekyll-paginate"

config.yml에서 활성화:

1
2
3
4
5
6
7
8

gems:
  - jekyll-feed
  - jekyll-paginate

#페이지 활성화
paginate: 6

Custom Domain

github page를 github.io 서브도메인 대신 본인의 도메인에 등록하려면 두 가지를 한다:

• 깃헙 페이지의 설정에서 custom domain 을 추가한다.
• DNS에 CNAME을 등록한다.

Custom domain 추가

github 에서 github page 저장소의 Settings 에서 Custom Domain에 사용할 도메인 이름을 저장한다.

CNAME 등록

DNS에 CNAME 을 github의 USER_NAME.github.io 에 연결해 준다.
제대로 등록됐는지 dig 명령으로 확인한다.

1
2
3
4
5

$ dig docs.example.com +nostats +nocomments +nocmd
;docs.example.com.                     IN      A
docs.example.com.              3592    IN      CNAME   YOUR-USERNAME.github.io.
YOUR-USERNAME.github.io.           43192   IN      CNAME  < GITHUB-PAGES-SERVER >.
  < GITHUB-PAGES-SERVER >.      22      IN      A       199.27.XX.XXX

참조: https://help.github.com/articles/setting-up-a-custom-subdomain/

이 글은 github pages 를 통해서 블로그를 할 수 있도록 다음 작업을 한다:

• 로컬에 ruby를 기반으로한 jekyll 을 설치한다.
• markdown 으로 작성한 문서를 github pages 에 올린다.

jekyll

jekyllrb.com 의 가이드에 따라 github page에서 블로그로 사용하고자 한다.