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

Если у вас возникли проблемы с установкой или использованием 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

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

gem install jekyll

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

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

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

# Ruby exports

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

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

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

Чтобы активировать новые экспорты, перезапустите 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

С появлением защиты целостности системы (SIP) в v10.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, etc.) для установки Jekyll.

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

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

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

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

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

Не удалось найти движок JavaScript. (ExecJS::RuntimeUnavailable)

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

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

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

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

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

jekyll serve --baseurl '/blog'

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

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

Не будет работать просто обратиться к:

http://localhost:4000/blog

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

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

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

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

Примечание: начиная с версии v3.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

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

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

Выдержки

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

Проблемы с производственной средой

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

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

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