Установка

Jekyll v3.x требует Ruby версии 2.0.0 и выше. Скачать можно здесь: http://rubyinstaller.org/downloads/. Так же необходимо установить Ruby DevKit по ссылке выше. Выбирать дистрибутивы необходимо той же разрядности, что и ОС.

Настраиваем Ruby DevKit:

cd C:\RubyDevKit
ruby dk.rb init
ruby dk.rb review

Подключаем DevKit к Ruby:

ruby dk.rb install

Устанавливаем Jekyll с зависимостями:

gem install jekyll bundler

Устанавливаем часто используемые возможности для Jekyll:

gem install jekyll-paginate-v2
gem install jekyll-feed
gem install jekyll-gist
gem install jekyll-tagging

Для возможности непрерывного посторения сайта на Windows (комманда: jekyll build --watch) необходимо установить gem wdm:

gem install wdm

Создание проекта сайта

c:\MySites>jekyll new blog.test

New jekyll site installed in c:/MySites/blog.test.
Running bundle install in c:/MySites/blog.test...
Fetching gem metadata from https://rubygems.org/............
Fetching version metadata from https://rubygems.org/...
Fetching dependency metadata from https://rubygems.org/..
Resolving dependencies...
Using public_suffix 3.0.0
Using colorator 1.1.0
Using ffi 1.9.18 (x64-mingw32)
Using forwardable-extended 2.6.0
Using rb-fsevent 0.10.2
Using kramdown 1.15.0
Using liquid 3.0.6
Using mercenary 0.3.6
Using rouge 1.11.1
Using safe_yaml 1.0.4
Using bundler 1.14.5
Using addressable 2.5.2
Using rb-inotify 0.9.10
Using pathutil 0.14.0
Using sass-listen 4.0.0
Using listen 3.0.8
Using sass 3.5.1
Using jekyll-watch 1.5.0
Using jekyll-sass-converter 1.5.0
Using jekyll 3.3.1
Using jekyll-feed 0.9.2
Using minima 2.1.1
Bundle complete! 3 Gemfile dependencies, 22 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

Генерация сайта

c:\MySites\blog.test>jekyll build
WARN: Unresolved specs during Gem::Specification.reset:
      rb-fsevent (>= 0.9.4, ~> 0.9)
      rb-inotify (>= 0.9.7, ~> 0.9)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
Configuration file: c:/MySites/blog.test/_config.yml
            Source: c:/MySites/blog.test
       Destination: c:/MySites/blog.test/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 3.327 seconds.
 Auto-regeneration: disabled. Use --watch to enable.

Для моего примера правим baseurl: "/blog.test" в _config.yml, размещаем на сервере и получаем:

Структура исходников сайта

  • _includes/ - каталог с готовыми кусками html для вставки
  • _layouts/ - каталог сшаблонами
    • default.html - основной шаблон
    • post.html - шаблон поста
  • _posts/ - каталог с постами
  • _site/ - каталог со сгенерированным сайтом
  • _config.yml - Файл конфигурации
  • 404.html
  • about.html
  • index.html

Шаблоны работают с помощью Liquid. Так например, может выглядеть список всех постов в блоге:

\{\% for post in site.posts \%\}
  <li><span>\{\{ post.date | date_to_string \}\}</span> &raquo; <a href="\{\{ post.url \}}\">\{\{ post.title \}\}</a></li>
\{\% endfor \%\}

Названия для постов требует строго форматирования аля год–месяц–день–name.format Формат: textile или markdown.

Пост должен включать шапку, обозначающую шаблон:

---
layout: post
title: "Название поста"
---

Парсер Markdown разметки и подсветка синтаксиса

Я использую redcarpet для парсинга Markdown разметки. Установка для версии Ruby 2.0.0 и выше:

gem install redcarpet -v 3.4.0

Прописываем в _config.yml:

markdown: redcarpet

redcarpet:
    extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"]

Для подсветки синтаксиса можно использовать Rogue:

gem install rogue

Прописываем в _config.yml:

highlighter: rouge

Но он мне не очень понравился и я останавился на Pygments. Для его работы требуется Python 2.7. Инсталятор взять можно здесь: http://www.python.org/download/. Так же желательно установить pip для Python: https://pip.pypa.io/en/latest/installing.html.

Совет дня. На GitHub с 1 мая 2016 года поддерживается только kramdown и rogue.

Переходим в каталог со скаченным get-pip.py и запускаем его:

cd C:\pip
python get-pip.py

Устанавливаем сам Pygments:

python -m pip install Pygments

Прописываем в _config.yml:

highlighter: pygments

Для правильной работы с файлами в кодировке UTF-8 with BOM, прописываем в _config.yml:

encoding: bom|utf-8

Совет дня. Лучше работать с файлами в кодировке UTF-8 без BOM.

Отображение контента

Тэги

Включаем плагин в файле _plugins/ext.rb:

Прописываем в _config.yml:

tag_page_layout: tag_page
tag_page_dir: tag
tag_permalink_style: pretty

И создаем шаблон страницы с тэгами в _layout/tag_page.html.

Связанные статьи

Связанные статьи и постах по умолчанию берутся из не более 10 последних постов, но для получения более релевантного результата можно воспользоваться опцией ---lsi во время запуска построения сайта.

jekyll build --watch --lsi --incremental

Если потребуется, то нужно установить gem:

gem install classifier-reborn

Количество связанных статей указывается в шаблоне _layouts/post.html

{/% for post in site.related_posts limit:5 /%}

Спойлер

Создаем плагин в файле _plugins/spoilerblock.rb со следующим содержимым:

module Jekyll
  class SpoilerBlock < Liquid::Block
    def initialize (tag_name, markup, tokens)
      super
      @summary = markup.strip
    end

    def render(context)
      output = '<details>'
      output << "<summary>#{@summary.empty? ? 'Open' : @summary}</summary>"
      output << super
      output << '</details>'
    end
  end
end

Liquid::Template.register_tag('spoilerblock', Jekyll::SpoilerBlock)

Для того что бы скрыть часть страницы под спойлер, нужно вставить блок:

{/% spoilerblock Название спойлера /%}

...

{/% endspoilerblock /%}

Ссылки