Обновление с версии 2.x до 3.x

В версии 3.0, вышедшей осенью 2015 года добавлен целый ряд важных изменений:

  • инкрементальная сборка, то есть сборка только измененных страниц сайта, доступна с флагом --incremental в качестве экспериментальной возможности
  • профилировщик Liquid
  • API хуков для разработки плагинов
  • уменьшено количество зависимостей с 14 до 8
  • прекращена поддержка Ruby 1.9.3, добавлена поддержка Ruby 2.2 и базовая поддержка JRuby
  • удален процессор markdown maruku

Изменения коллекций

В версии 2.x при итерации через site.collections, каждая коллекция была массивом, первый элемент которой был меткой коллекции, а вторым элемент объект коллекции. В версии 3.x эта сложность устранена и итерация проходит только через сам объект коллекции, теперь:

  • collection[0] это collection.label
  • collection[1] это collection

Учитывайте это в ваших шаблонах при итерации site.collections.

Исключенные зависимости

Многие пакеты, ранее включавшиеся в ядро, теперь стали опциональными. Теперь для их использования их надо установить и подключить в _config.yml. Это следующие пакеты:

  • jekyll-paginate – модуль Jekyll для разбивки на страницы
  • jekyll-coffeescript – процессор CoffeeScript
  • jekyll-gist – тег Liquid gist
  • pygments.rb – подсветчик синтаксиса Pygments
  • redcarpet – процессор Markdown
  • toml – альтернативный YAML формат конфигурационных файлов
  • classifier-reborn – длч выборки связанных постов site.related_posts

Отложенные посты

В версии 2.x флаг --future был по умолчанию активирован. Этот флаг позволяет авторам датировать посты будущим временем и исключать эти посты из сборки до его наступления. Сейчас этот флаг по умолчанию отключен и это значит, что если вы хотите сгенерировать отложенные посты, вам надо прямо указать опцию --future при выполнении jekyll build или jekyll serve.

Метаданные макетов

В Jekyll 2 и ниже все метаданные макетов терялись для переменной page. Это влекло множество недоразумений при вложении макетов и влекло неожиданное поведение. В Jekyll 3 все данные макетов доступны через переменную layout. Например, если во вводной макета есть class: my-layout, эти данные можно извлечь через layout.class.

Смена подсветчика синтаксиса

В третье версии Rouge заменил Pygments в качестве подсветчика и тепеоь некоторые функции тега highlight не работают по умолчанию, например, hl_lines. Чтобы вернуться к Pygments, вам надо добавить в _config.yml строчку highlighter: pygments и установить гем командой gem install pygments.rb или добавить в гемфайл проекта gem 'pygments.rb'.

Удалена поддержка относительных пермалинков

В Jekyll 3 и выше относительные пермалинки отключены. Если вы создавали сайт с Jekyll 2 и ниже вы можете получить следующую ошибку при запуске сборки или локального сервера:

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

Это можно исправить, удалив следующую строчку из файла _config.yml:

relative_permalinks: true

Теперь закрывающий слэш не добавляется в пермалинки автоматически

В Jekyll 2 ко всем URL, конструируемым на основе заданного поля permalink: закрывающий слэш добавлялся автоматически. Jekyll 3 автоматически не добавляет закрывающий слэш к пермалинкам. Потенциально это может повлечь ошибку 404 в старых ссылках на страницы. Например, представьте страницу, содержащую во вводной permalink: /:year-:month-:day-:title — это создает URL example.com/2016-02-01-test/. В Jekyll 3 тот же permalink: сгенерирует файл 2016-02-01-test.html, адрес страницы будет example.com/2016-02-01-test и, соответственно, все ссылки на старый URL будут приводить к ошибке 404. Для решения этой проблемы надо добавить закрывающий слэш вручную, например, permalink: /:year-:month-:day-:title/.

Все мои посты пропали! Что делать?

Попробуйте добавить опцию future: true в файл _config.yml. Появились? Если так, то вы столкнулись с особенностями того, как Ruby парсит время. Каждый из постов был считан во временной зоне, отличной от ожидаемой исходя из времени на компьютере. Исправить это можно добавив сдвиг для временной зоны к каждому посту (и удалив опцию future: true из _config.yml). Если вы пишете из Калифорнии, то вам надо заменить этот вариант:

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

На этот:

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

Мои категории не работают!

Если вы упорядочиваете категории путем создания подкаталогов типа /_posts/code/2008-12-24-closures.md, то вам надо поменять местами папку категории и папку постов, вот так: /code/_posts/2008-12-24-closures.md.

Обновление с версии 0.x до 2.x

Как обновить старую версию Jekyll? Некоторые вещи поменялись со времени версии 1.0 и вам стоит узнать об этом.

Для начала установите последнюю версию Jekyll на компьютер:

$ gem update jekyll
Простой вариант

Хотите быстро создать новый сайт на Jekyll? Просто выполните команду jekyll new SITENAME, чтобы создать новый каталог с заготовкой сайта

Команда Jekyll

Для ясности — Jekyll принимает команды build иserve. Если раньше вы просто запускали команду Jekyll для генерации сайта и jekyll --server для локального предпросмотра сайта, то с версии 2.0 вы используете для этого субкоманды jekyll build и jekyll serve.

Локальный сервер

С новыми субкомандами предпросмотр локальных сайтов немного изменился. Вместо задания в конфигурации ` server: true используйте jekyll serve. То же относится и к watch: true используйте флаг –watch с jekyll serve или jekyll build`

Абсолютные пермалинки

В Jekyll v1.0 впервые появились абсолютные пермалинки для страниц в подкаталогах. Начиная с версии 2.0, абсолютные пермалинки стали дефолтными вместо относительных. Обратная совместимость относительных пермалинков будет удалена в версии 3.0.

Абсолютные пермалинки будут обязательными с версии 3.0

Начиная с версии Jekyll 3.0 относительные пермалинки будут полностью удалены и станут недоступными для использования

Черновики

В Jekyll есть возможность создания черновиков с локальным предпросмотром. Для создания черновика просто создайте каталог _drafts в основном каталоге сайта и добавьте туда новый файл с разметкой. Для предпросмотра черновиков просто выполните jekyll serve с флагом --drafts.

У черновиков нет дат

В отличие от постов, черновики не датируются, так как они не опубликованы. Поэтому вместо стандартного именования 2013-07-01-my-draft-post.md именуйте черновики просто по названию поста my-draft-post.md

Кастомный файл конфигурации

Вместо задания индивидуальных флагов при запуске вы можете передать целый кастомный файл с конфигурацией. Это упрощает разделение между окружениями и позволяет вам программно переопределять умолчания. Просто добавьте флаг --config к команде jekyll и путь к одному или нескольким конфигурационным файлам.

Соответственно, следующие старые флаги командной строки сейчас запрещены:

Permalink

  • --no-server
  • --no-auto (сейчас --no-watch)
  • --auto (сейчас --watch)
  • --server
  • --url=
  • --maruku, --rdiscount и --redcarpet
  • --pygments
  • --permalink=
  • --paginate
Флаг --config явно указывает конфигурационный файл

Если вы используете флаг --config, Jekyll будет игнорировать ваш файл _config.yml. Хотите совместить кастомную конфигурацию с обычной? Не проблема, Jekyll принимает больше одного файла при конфигурации в командной строке. Файлы конфигурации каскадируются справа налево, поэтому команда jekyll serve --config _config.yml,_config-dev.yml позволит файлу _config-dev.yml переписать настройки _config.yml, когда они содержат один ключ

Новые опции конфигурационного файла

В Jekyll 1.0 представлено несколько новых опций конфигурационного файла. Перед обновлением проверьте, присутствуют ли они в вашем старом файле конфигурации и если да, убедитесь, что вы используете их правильно:

  • excerpt_separator
  • host
  • include
  • keep_files
  • layouts
  • show_drafts
  • timezone
  • url

Базовый URL

У многих возникает желание запускать сайт на Jekyll в различных местах, например локально просматривать перед развертыванием на GitHub Pages. Jekyll 1.0 облегчает это с новым флагом --baseurl. Чтобы использовать преимущества этой фичи, сначала добавьте baseurl продакшен-версии вашего сайта в _config.yml. Затем на всем сайте добавьте относительный URL префикс {{ site.baseurl }}. А для локального предпросмотра передайте --baseurl с локальным базовым URL (обычно это /) команде jekyll serve и все ваши ссылки будут работать правильно в обоих окружениях.

!!Все URL страниц и постов содержат открывающий слэш

Если вы используете метод, указанный выше, запомните, что все URL страниц и постов содержат открывающий слэш. А значит, конкатенация базового URL c URL поста, где site.baseurl = / и post.url = /2013/06/05/my-fun-post/ даст в результате два открывающих слэша, что поломает ссылки. Таким образом предполагается, что префикс site.baseurl используется тогда, когда baseurl отличается от дефолтного /.