トラブルシューティング
Jekyllのインストールまたは使用中に問題が発生した場合は、以下のヒントが役立つ場合があります。発生している問題が以下で説明されていない場合は、他のヘルプリソースもご覧ください。
インストールの問題
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'
GentooにRubyGemsをインストールするには
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 on Ubuntu on Windowsのほとんどのフレーバーでは、.bashrcファイルの最後に次の行を追加することで、非スーパーユーザーとして、gemをシステム全体にインストールすることなくJekyllを実行できます。
# Ruby exports
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH
これは、gemにgemをシステム全体の場所ではなくユーザーのホームフォルダー内に配置するように指示し、ローカルのjekyllコマンドをシステム全体のパスよりも前にユーザーのPATHに追加します。
これは、ユーザーアカウントの権限が限られている多くの共有ウェブホスティングサービスにも役立ちます。.bashrcにこれらのエクスポートを追加してからgem install jekyll bundlerを実行すると、sudoを使用せずに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
v10.11でシステム整合性保護が導入されたことで、以前は書き込み可能だったいくつかのディレクトリがシステムの場所と見なされ、使用できなくなりました。これらの変更を考慮すると、起動して実行するための簡単な方法がいくつかあります。1つのオプションは、gemがインストールされる場所を変更することです（ここでも、sudoは必要な場合のみ使用します）。
gem install -n /usr/local/bin jekyll
または、HomebrewをインストールしてRubyを設定するために使用できます。これは次のように実行できます。
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Homebrewがインストールされたら、2番目の手順は次を実行することです。
brew install ruby
上級ユーザー（より複雑なニーズを持つユーザー）は、Jekyllをインストールするために、多数のRubyバージョンマネージャー（RVM、rbenv、chruby、など）のいずれかを選択すると役立つ場合があります。
上記のいずれかの方法を使用してRubyをインストールすることを選択した場合は、次のコマンドを使用して$PATH変数を変更する必要がある場合があります。
export PATH=/usr/local/bin:$PATH
GUIアプリは、次のように$PATHを変更できます。
launchctl setenv PATH "/usr/local/bin:$PATH"
これらのアプローチはいずれも、/usr/localがSIPが有効になっているシステムでは「安全な」場所と見なされているため、Appleによって含まれているRubyのバージョンとの潜在的な競合を回避し、Jekyllとその依存関係をサンドボックス環境に保つため、役立ちます。これには、gemを追加または削除するときにsudoを必要としないという追加の利点もあります。
JavaScriptランタイムが見つかりませんでした。(ExecJS::RuntimeUnavailable)
このエラーは、適切なJavaScriptランタイムがない場合にjekyll-coffeescriptのインストール中に発生する可能性があります。これを解決するには、execjsとtherubyracer gemをインストールするか、nodejsをインストールします。詳細については、issue #2327をご覧ください。
Jekyllの実行に関する問題
macOS
Jekyllは、ARM64アーキテクチャのmacOSと互換性があります。ただし、bundle exec jekyll serveは古いバージョンのffiで失敗する可能性があります。
bundle updateを実行するか、ffiを少なくとも1.14.2に手動で更新する必要がある場合があります。
DebianまたはUbuntu
DebianまたはUbuntuでは、ターミナルでjekyll実行ファイルを使用できるようにするために、パスに/var/lib/gems/1.8/bin/を追加する必要がある場合があります。
ベース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にも渡します。これにより、参照が存在しない、またはタグが閉じられていないという奇妙なエラーが発生する可能性があります。これらのエラーが発生した場合は、_config.ymlでexcerpt_separator: ""を設定するか、ナンセンスな文字列に設定してみてください。
本番環境での問題
v3.2.0以降、本番環境のビルド中に静的ファイルが見つからないという問題が発生した場合は、環境をproductionに設定する必要があります。この問題は、存在しないシンボリックリンクをコピーしようとしたことが原因です。
発生した問題は報告してください！
バグを発見した場合は、GitHubでissueを作成して、問題と見つかった回避策を説明してください。そうすれば、ここで他のユーザーのために文書化できます。