Устранение неполадок

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

Проблемы с установкой
Проблемы при запуске Jekyll
Проблемы с базовым URL
Проблемы с конфигурацией
Проблемы с разметкой
Проблемы в рабочей среде

Проблемы с установкой

Если при установке gem возникают ошибки, возможно, вам потребуется установить заголовочные файлы для компиляции модулей расширения для Ruby 2.x. В Ubuntu или Debian это можно сделать, выполнив команду:

sudo apt-get install ruby2.6-dev

В системах Red Hat, CentOS и Fedora это можно сделать, выполнив команду:

sudo yum install ruby-devel

В Arch Linux выполните команду:

sudo pacman -S ruby-ffi

В Ubuntu, если после bundle exec jekyll serve вы столкнулись с ошибками и видите сообщения вроде Could not locate Gemfile или .bundle/ directory, скорее всего, это связано с тем, что выполнены не все необходимые условия. В последних стандартных дистрибутивах Ubuntu требуется установить пакеты ruby и ruby-all-dev:

sudo apt-get install ruby ruby-all-dev

В NearlyFreeSpeech перед установкой Jekyll необходимо выполнить следующие команды:

export GEM_HOME=/home/private/gems
export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
export PATH=$PATH:/home/private/gems/bin
export RB_USER_INSTALL='true'

Чтобы установить RubyGems в Gentoo:

sudo emerge -av dev-ruby/rubygems

В Windows может потребоваться установить RubyInstaller DevKit.

В Android (с Termux) все необходимые компоненты можно установить, выполнив команду:

apt update && apt install libffi-dev clang ruby-dev make

В macOS может потребоваться обновить RubyGems (используя sudo только при необходимости):

gem update --system

Если проблемы сохраняются, можно загрузить и установить новые инструменты командной строки (например, gcc), выполнив следующую команду:

xcode-select --install

Это может позволить установить нативные gems с помощью следующей команды (снова используя sudo только при необходимости):

gem install jekyll

Обратите внимание: обновление macOS не приводит к автоматическому обновлению самого Xcode (это можно сделать отдельно через App Store), а устаревший Xcode.app может мешать работе загруженных выше инструментов командной строки. Если вы столкнулись с этой проблемой, обновите Xcode и установите обновлённые инструменты командной строки.

Запуск Jekyll без прав суперпользователя (без sudo!)

В большинстве дистрибутивов Linux, в macOS и в Bash on Ubuntu on Windows можно запускать Jekyll без прав суперпользователя и без установки gems в системные каталоги. Для этого добавьте следующие строки в конец файла .bashrc:

# Ruby exports

export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH

Это указывает gem размещать gems в домашней папке пользователя, а не в системном каталоге, и добавляет локальную команду jekyll в переменную PATH пользователя перед всеми системными путями.

Это также полезно для многих служб общего веб-хостинга, где учётные записи пользователей имеют ограниченные права. Добавление этих экспортируемых переменных в .bashrc перед запуском gem install jekyll bundler позволяет установить Jekyll без использования sudo.

Чтобы применить новые экспортируемые переменные, закройте и перезапустите Bash, выйдите из учётной записи оболочки и войдите снова либо выполните . .bashrc в текущей оболочке.

Если при выполнении команды jekyll new вы видите следующую ошибку, её можно устранить описанным выше способом:

jekyll new test

Running bundle install in /home/user/test...

Your user account is not allowed to install to the system RubyGems.
You can cancel this installation and run:

    bundle install --path vendor/bundle

to install the gems into ./vendor/bundle/, or you can enter your password
and install the bundled gems to RubyGems using sudo.

Password:

После этого команда jekyll new должна правильно работать для вашей учётной записи.

Jekyll и macOS

С появлением System Integrity Protection в версии 10.11 несколько каталогов, доступных для записи ранее, теперь считаются системными и больше недоступны. С учётом этих изменений есть несколько простых способов начать работу. Один из вариантов — изменить каталог установки gem (снова используя sudo только при необходимости):

gem install -n /usr/local/bin jekyll

Другой вариант — установить Homebrew и использовать его для настройки Ruby. Это можно сделать следующим образом:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

После установки Homebrew выполните второй шаг:

brew install ruby

Опытным пользователям (с более сложными потребностями) может быть полезно выбрать один из менеджеров версий Ruby (RVM, rbenv, chruby, и другие) для установки Jekyll.

Если вы выбрали один из описанных выше способов установки Ruby, может потребоваться изменить переменную $PATH с помощью следующей команды:

export PATH=/usr/local/bin:$PATH

В графических приложениях переменную $PATH можно изменить следующим образом:

launchctl setenv PATH "/usr/local/bin:$PATH"

Оба этих подхода полезны, поскольку /usr/local считается «безопасным» каталогом в системах с включённой SIP, они позволяют избежать возможных конфликтов с версией Ruby, поставляемой Apple, и сохраняют Jekyll и его зависимости в изолированной среде. Кроме того, при добавлении или удалении gem не потребуется использовать sudo.

Не удалось найти среду выполнения JavaScript. (ExecJS::RuntimeUnavailable)

Эта ошибка может возникнуть при установке jekyll-coffeescript, если у вас нет подходящей среды выполнения JavaScript. Чтобы устранить проблему, установите gems execjs и therubyracer либо установите nodejs. Подробнее см. в обсуждении № 2327.

Проблемы при запуске Jekyll

macOS

Jekyll совместим с macOS на архитектуре ARM64. Однако bundle exec jekyll serve может не работать со старой версией ffi.

Возможно, потребуется выполнить bundle update или вручную обновить ffi как минимум до версии 1.14.2.

Debian или Ubuntu

В Debian или Ubuntu может потребоваться добавить /var/lib/gems/1.8/bin/ в переменную PATH, чтобы исполняемый файл jekyll был доступен в терминале.

Проблемы с базовым URL

Если вы используете параметр base-url, например:

jekyll serve --baseurl '/blog'

… убедитесь, что открываете сайт по адресу:

http://localhost:4000/blog/index.html

Просто открыть его по адресу:

http://localhost:4000/blog

не получится.

Проблемы с конфигурацией

Приоритет конфликтующих параметров конфигурации определяется следующим образом:

Флаги командной строки
Параметры файла конфигурации
Значения по умолчанию

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

Примечание. Начиная с версии 3.3.0 Jekyll по умолчанию не обрабатывает node_modules и некоторые подкаталоги внутри vendor. Однако явное указание массива exclude: в файле конфигурации переопределяет это значение по умолчанию. В результате при сборке сайта у некоторых пользователей возникает ошибка со следующим сообщением:

    ERROR: YOUR SITE COULD NOT BE BUILT:
    ------------------------------------
    Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
    Document 'vendor/bundle/gems/jekyll-3.4.3/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb'
    does not have a valid date in front matter.

Добавление vendor/bundle в список exclude: решит эту проблему, но приведёт к обработке других подкаталогов внутри /vendor/ (а также /node_modules/, если он существует) и их копированию в целевой каталог _site.

Правильное решение — включить значение по умолчанию для exclude:, а не переопределять его целиком:

В версиях до v3.4.3 параметр exclude: должен выглядеть следующим образом:

exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor/bundle/
  - vendor/cache/
  - vendor/gems/
  - vendor/ruby/
  - any_additional_item # any user-specific listing goes at the end

Начиная с версии v3.5 каталоги Gemfile и Gemfile.lock также исключаются по умолчанию. Поэтому в большинстве случаев нет необходимости задавать в файле конфигурации ещё один массив exclude:. Существующее определение можно изменить, как описано выше, полностью удалить или закомментировать, чтобы его было проще отредактировать в будущем.

Проблемы с разметкой

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

Liquid

Похоже, версия 2.0 Liquid нарушает работу {{ в шаблонах. В отличие от предыдущих версий, использование {{ в версии 2.0 вызывает следующую ошибку:

'{{' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)

Отрывки

Начиная с версии 1.0.0 Jekyll автоматически создаёт отрывки записей. Начиная с версии 1.1.0 Jekyll также обрабатывает эти отрывки с помощью Liquid. Это может приводить к неожиданным ошибкам, например, если ссылка не существует или тег не закрыт. Если вы столкнулись с такими ошибками, попробуйте задать excerpt_separator: "" в файле _config.yml или указать для него бессмысленную строку.

Проблемы в рабочей среде

Если начиная с версии 3.2.0 при сборке в рабочей среде вы столкнулись с тем, что статический файл не найден, задайте для окружения значение production. Проблема возникает из-за попытки скопировать несуществующую символическую ссылку.

Сообщайте о проблемах, с которыми вы столкнулись!

Если вы обнаружили ошибку, пожалуйста, создайте обращение на GitHub, описав проблему и найденные обходные решения, чтобы мы могли задокументировать их здесь для других пользователей.