Базовая настройка Jekyll

При установке блога на Jekyll уже были кратко описаны некоторые обязательные действия, такие как смена названия и URL сайта на актуальные.

Здесь эти вопросы будут разобраны подробнее, с примерами для сайта на Github Pages.

TL;DR; Свежая установка Jekyll - cмотри чек-лист. Внесение серьёзных модификаций, fork репозитория, установка "с нуля", по гайду из интернета (включая мой) или по официальной инструкции - неважно. Перестало работать - cмотри чек-лист. Если ничего не помогло, читай документацию (Jekyll и хостера).

Итак, цель - сделать, чтобы сайт (блог, магазин, площадка - не суть) на Jekyll заработал. Пусть он установлен в "рабочий каталог", т.е. выделенную папку, которая теперь содержит файл _config.yml. Все пути будут начинаться от этой папки.

Чек-лист

1. проверить работоспособность Jekyll,
2. проверить/настроить файл _config.yml и YAML,

Дополнительно при первой установке рекомендуется

1. очистить привязки к предыдущему владельцу, в том числе убрать из HTML-кода счётчики/трекеры,
2. удалить старые записи,
3. настроить локальный Jekyll для отладки.
4. (опционально) создать и персонализировать специальные страницы (типа /about).
5. (опционально) организовать файловую структуру для хранения дополнительных файлов.
6. (опционально) при развёртывании на Github Pages учесть особенности настройки Jekyll.

Минута теории: для запуска Jekyll для формирования сайта достаточно... иметь один-единственный файл _config.yml в основном каталоге. И, само собой, установленный Jekyll.

Работоспособность Jekyll

Для отладки крайне рекомедуется установить Jekyll локально. Первоочередная задача - проверить, что Jekyll успешно транслирует установленный/скопированный сайт в HTML-страницы.

Что может пойти не так:

• версия Jekyll, на которой сделан сайт:
  • не соответствует версии Jekyll хостера,
  • не соответствует локальной версии, используемой для отладки,
• требуемые плагины (см. _config.yml) или зависимости (Gemfile) недоступны,
• ошибки при анализе конфигурации (YAML),
• разнообразные проблемы в процессе создания (генерации) статических страниц (шаблонизатор Liquid).

Иногда Jekyll выдаёт предупреждения, которые тоже рекомендуется исправить.

Неверная версия Jekyll

Лучше всего узнать, какая версия Jekyll и какие плагины используются на хостинге, и прописать их явно в файл Gemfile (создать его при необходимости, пример для Github Pages чуть ниже).

Чтобы этот файл был учтён, нужен пакет bundler¹ Ruby, который проверяет Gemfile и подключает указанную версию Jekyll и нужные плагины. Подробнее см особенности локального запуска Jekyll.

Запускать Jekyll надо командой

>bundle exec jekyll serve

При этом лучше запускать его с дополнительным флагом --baseurl "", т.к. Jekyll может быть настроен на работу по адресу <сайт>/<base_url>/ (см. сайт проекта), а локально он запускается по адресу http://127.0.0.1:4000 (без пути <base_url>).

В случае с Github Pages этот файл предлагается создать с содержимым

source 'https://rubygems.org'  
gem 'github-pages', group: :jekyll_plugins

После запуска bundler (например, bundle install) будет создан файл Gemfile.lock, в котором будут перечислены конкретные подключаемые пакеты (gems) Ruby, включая плагины Jekyll.

Ошибки в YAML и Liquid

Половина проблем будет вызвана неправильным формированием YAML-данных (см. запись о формате YAML), а вторая половина - ошибками шаблонизатора Liquid (см. заметку о разметке Liquid).

Подробную информацию об ошибках можно получить, запустив Jekyll с параметром --trace, например

>bundle exec jekyll build --trace

Полный и детальный список ошибок, предупреждений и их решения для Jekyll можно найти в документации Github Pages.

В этих случаях чаще всего Jekyll откажется обрабатывать сайт. Опять же, проще всего это отловить с помощью локальной установки Jekyll и пробного запуска. Также можно получить детализированную информацию об ошибках в главном конфигурационном файле _config.yml командой

>bundle exec jekyll doctor

Желательно заодно проверить и правильность заголовков Front Matter (YAML-разметка в начале большинства страниц), включив жёсткий контроль флагом --strict_front_matter:

>bundle exec jekyll build --strict_front_matter

или сразу добавив эквивалентный параметр strict_front_matter: true в _config.yml.

При редактировании и создании YAML-кода рекомендую использовать один из валидаторов разметки из записи о YAML.

Главный файл настроек _config.yml

Этот файл практически всегда надо настраивать. Если нет уверенности в формате, при редактировании не забывать про валидаторы разметки YAML.

Конфигурационный файл _config.ymlсодержит словарь (структуру), неявно включающие предопределённые поля и их значения по умолчанию, так и пользовательские поля. В документации Jekyll есть полное описание настроек².

В последующем этот словарь имеет имя site и может использоваться в шаблонах Liquid (например, site.title выдаст значение поля title: в _config.yml).

При редактировании этого файла надо перезапускать сервер Jekyll (bundle exec jekyll serve), иначе изменения не будут учтены.

Github Pages переопределяет значения по умолчанию ряда полей, а также фиксирует некоторые поля.

Разнообразие пользовательских полей, как правило, используется для настройки темы или самого сайта. Конфигурационный файл этого блога содержит некоторые полезные комментарии.

Первоочередные действия

• изменить автора (поле author:) - это необязательное. но типичное поле
• изменить название сайта/блога (поле title:)
• сменить URL блога на новый (URL: и baseurl:). Строка baseurl: показывает путь к блогу относительно корня сайта, что необходимо при настройке сайтов проектов. Github Pages заполняет эти поля автоматически, с помощью плагина GitHub Metadata.

Настройка плагинов

Задаётся словарём в поле plugins:. Ранее поле называлось gems:, о чём Jekyll предупреждает сообщением при запуске старых тем/сайтов:

   Deprecation: The 'gems' configuration option has been renamed to 'plugins'. Please update your config file accordingly.

Несмотря на множество плагинов, их использование не включается автоматически. Во-первых, они должны быть установлены в Ruby как модули (gems). Например, это можно сделать с помощью функционала bundler с помощью Gemfile; (текущий список можно посмотреть в Gemfile.lock). Во-вторых, они должны быть активированы в разделе plugins: конфигурационного файла.

Для Github Pages набор плагинов ограничен, причём часть из них включена по умолчанию.

Есть третий способ установки плагинов - поместить rb-файл (Ruby) в специальную папку (по умолчанию _plugins), но эта возможность отключена в Github Pages по соображениям безопасности.

Отвязывание от предыдущего владельца

Актуально при клонировании блога с понравившейся темой (или после fork в Github). Иногда информация о сбросе настроек есть в README файле репозитория темы.

В любом случае рекомендую сделать следующие шаги, после каждого шага проверяя работоспособность сайта:

• отменить или изменить приязку к конкретному домену, удалив или отредактировав файл CNAME в корне.
• изменить Google Analytics ID в _config.yml, если тема сайта явно его предусматривает, например, как этот блог.
• просмотреть HTML-код сайта на предмет трекеров (можно смотреть шаблоны, а можно - собранный Jekyll-ом сайт в _site). В этом блоге используется Google Analytics, настраиваемый в _config.yml.
• удалить "чужие" записи,
• (с осторожностью!) убрать "лишние" пользовательские переменные, если они не используются в шаблонах,
• настроить специальные страницы (/about и пр.)

Ссылки

• https://help.github.com/en#troubleshooting-github-pages-builds - решение проблем с Jekyll в документации Github Pages.

• https://pages.github.com/versions/ - версии Jekyll и его плагинов/тем, используемых в Github Pages.

• https://jekyllrb.com/docs/configuration/ - документация по конфигурации Jekyll.

• https://help.github.com/en#customizing-github-pages - раздел по Jekyll в помощи Github Pages.

• заметка по YAML - список валидаторов YAML в конце заметки.

• https://guides.hexlet.io/jekyll/#_configyml - краткое введение в основные параметры файла конфигурации.