Improve this page

トラブルシューティング

Jekyllのインストールや使用に関する問題に出会ったら、ここにいくつかのヒントがあります。あなたが経験している問題が以下でカバーされていなければ、他のヘルプリソースをチェックしてください。

インストールの問題

gemのインストール時にエラーに遭遇したら、Ruby 2.x用コンパイルの拡張モジュールのヘッダファイルをインストールする必要があります。UbuntuやDebianでは次を実行します。

sudo apt-get install ruby2.6-dev

Red Hat, CentOS, そしてFedoraでは、次を実行します。

sudo yum install ruby-devel

上記をインストールしたが、 - 特にFedora 23で - 拡張機能がまだコンパイルしない場合は、おそらくredhat-rpm-configが欠けているFedora imageを実行しているのでしょう。解決するために次を実行します。

sudo dnf install redhat-rpm-config

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 (with Termux)では全ての必要要件を次の実行でインストールできます。

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

macOSでは、RubyGemsのアップデートが必要かもしれません（必要な場合だけsudoを使用します）。

gem update --system

まだ問題があるのでしたら、（gccのような）新しいコマンドラインツールを以下のコマンドでインストールしてください。

xcode-select --install

これにより、このコマンド（必要な場合だけsudoを使用します）でネイティブgemsをインストールできるようになります。

gem install jekyll

macOSのアップグレードは自動でXcodeをアップグレードしません（App Storeで別途行えます）、古いXcode.appは上記でダウンロードしたコマンドラインツールを妨害する恐れがあります。この問題に直面している場合は、Xcodeをアップグレードし、アップグレードされたコマンドラインツールをインストールしてください。

Non-SuperuserとしてJekyllを実行する (no sudo!)

Linux、macOS、およびWindows上のUbuntuのBashのほとんどのフレーバーでは、次の行を.bashrcファイルの末尾に追加することで、Jekyllをnon-superuserとして実行し、システム全体の場所にgemをインストールする必要はありません。

# Ruby exports

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

これは、gemの場所をシステム全体の場所ではなく、ユーザーのホームフォルダのgemsにし、システム全体のパスよりもユーザーのPATHにlocal jekyllコマンドを追加します。

これは、ユーザーアカウントの権限が限られている多くの共有Webホスティングサービスにも役立ちます。gem install jekyll bundlerを実行する前に、これらのexportを.bashrcに追加すると、Jekyllを完全にnon-sudoでインストールできます。

新しいexportを有効にするには、Bashを閉じ再起動するか、shellアカウントからログアウトしてログインしなおすか、実行中のshellで. .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でのSystem Integrity Protectionの導入により、以前は書き込み可能だったいくつかのディレクトリがシステムの場所と見なされ、使用できなくなりました。これらの変更を受け、起動して実行するにはいくつかの簡単な方法があります。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, etc.）のうちの1つを選ぶのが役に立つかもしれません。

Rubyのインストールに上記の方法のいずれかを使用することを選択した場合は、次のコマンドを使用して$PATH変数を変更する必要がある場合があります。

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

GUI appsは以下で$PATHを修正できます。

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

SIPが有効になっているシステムでは/usr/localが「安全な」場所と見なされ、Appleが提供するRubyのバージョンとの潜在的な競合を回避し、Jekyllとその依存関係をサンドボックス環境に保ちます。gemを追加または削除するときにsudoを必要としないという利点もあります。

JavaScriptランタイムが見つけられない。(ExecJS::RuntimeUnavailable)

適切なJavaScriptランタイムがない場合、jekyll-coffeescriptのインストール中にこのエラーが発生する可能性があります。これを解決するには、execjsとtherubyracer gemsをインストールするか、nodejsをインストールしてください。 詳細はissue #2327をご覧ください。

Jekyll実行の問題

DebianやUbuntuでは、jekyll実行ファイルをターミナルで利用できるようにするために、パスに/var/lib/gems/1.8/bin/を追加する必要があります。

Base-URLの問題

jekyll serve --baseurl '/blog'

上記のようにbase-urlオプションを使用している場合、サイトへのアクセスは以下を使用します。

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

以下では上手く機能しません。

http://localhost:4000/blog

設定の問題

構成・設定で矛盾がある場合の優先順位は以下の通りです。

  1. コマンドラインのflags
  2. 設定ファイルの設定
  3. デフォルト

これは、デフォルトは_config.ymlのオプション設定で上書きされ、コマンドラインのflagsは他の設定を上書きするを意味しています。

注：v3.3.0以降、Jekyllはデフォルトでnode_modulesとvendor内の特定のサブディレクトリを処理しません。ただし、設定ファイルで明示的にexclude:arrayを定義すると、このデフォルト設定が上書きされるため、一部のユーザーはサイトの構築時にエラーが発生し、次のエラーメッセージが表示されます。

    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:arrayを定義する必要はありません。そのため、既存の定義を上記のように変更するか、完全に削除するか、コメントアウトして簡単に編集できるようにすることができます。

マークアップの問題

Jekyllが使用している複数のマークアップエンジンにはいくつか問題があります。このページは同じ問題に直面している方への助けとなるでしょう。

Liquid

Liquidバージョン2.0はテンプレートでの{{の使用が壊れています。以前のバージョンとは異なり、2.0で{{の使用は以下のエラーを発生させます。

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

Excerpts（抜粋）

v1.0.0以降、Jekyllは自動的にポストの抜粋を生成しています。v1.1.0以降、Jekyllはこれらの抜粋をLiquidに渡していますが、参照が存在しない場合やタグが閉じられていない場合に、奇妙なエラーを引き起こす可能性があります。これらのエラーが発生した場合は、_config.ymlにexcerpt_separator: ""を設定するか、または無意味な文字列を設定してください。

productionの問題

v3.2.0以降のビルド中にproduction環境で静的ファイルが見つからないという問題が発生した場合は、environmentをproductionに設定する必要があります。この問題は、存在しないシンボリックリンクをコピーしようとしたことが原因です。

遭遇した問題を報告してください！

バグに遭遇した場合は、GitHubで問題とその回避策を説明したissueを作成してください。そうすればここで他の人のために文書化することができます。