•  


Troubleshooting | Jekyll ? Simple, blog-aware, static sites

Troubleshooting

If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.

Installation Problems

If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for Ruby 2.x This can be done on Ubuntu or Debian by running:

sudo 
apt-get 
install 
ruby2.6-dev

On Red Hat, CentOS, and Fedora systems you can do this by running:

sudo 
yum 
install 
ruby-devel

On Arch Linux you need to run:

sudo 
pacman 
-S
 ruby-ffi

On Ubuntu if you get stuck after bundle exec jekyll serve and see error messages like Could not locate Gemfile or .bundle/ directory , it’s likely because all requirements have not been fully met. Recent stock Ubuntu distributions require the installation of both the ruby and ruby-all-dev packages:

sudo 
apt-get 
install 
ruby ruby-all-dev

On NearlyFreeSpeech you need to run the following commands before installing 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'

To install RubyGems on Gentoo:

sudo 
emerge 
-av
 dev-ruby/rubygems

On Windows, you may need to install RubyInstaller DevKit .

On Android (with Termux) you can install all requirements by running:

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

On macOS, you may need to update RubyGems (using sudo only if necessary):

gem update 
--system

If you still have issues, you can download and install new Command Line Tools (such as gcc ) using the following command:

xcode-select 
--install

which may allow you to install native gems using this command (again, using sudo only if necessary):

gem 
install 
jekyll

Note that upgrading macOS does not automatically upgrade Xcode itself (that can be done separately via the App Store), and having an out-of-date Xcode.app can interfere with the command line tools downloaded above. If you run into this issue, upgrade Xcode and install the upgraded Command Line Tools.

Running Jekyll as Non-Superuser (no sudo!)

On most flavors of Linux, macOS, and Bash on Ubuntu on Windows, it is possible to run Jekyll as a non-superuser and without having to install gems to system-wide locations by adding the following lines to the end of your .bashrc file:

# Ruby exports


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

This tells gem to place its gems within the user’s home folder, not in a system-wide location, and adds the local jekyll command to the user’s PATH ahead of any system-wide paths.

This is also useful for many shared webhosting services, where user accounts have only limited privileges. Adding these exports to .bashrc before running gem install jekyll bundler allows a complete non- sudo install of Jekyll.

To activate the new exports, either close and restart Bash, logout and log back into your shell account, or run . .bashrc in the currently-running shell.

If you see the following error when running the jekyll new command, you can solve it by using the above-described procedure:

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:

Once this is done, the jekyll new command should work properly for your user account.

Jekyll & macOS

With the introduction of System Integrity Protection in v10.11, several directories that were previously writable are now considered system locations and are no longer available. Given these changes, there are a couple of simple ways to get up and running. One option is to change the location where the gem will be installed (again, using sudo only if necessary):

gem 
install
 -n
 /usr/local/bin jekyll

Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows:

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

Once Homebrew is installed, the second step is to run:

brew 
install 
ruby

Advanced users (with more complex needs) may find it helpful to choose one of a number of Ruby version managers ( RVM , rbenv , chruby , etc .) in which to install Jekyll.

If you elect to use one of the above methods to install Ruby, it might be necessary to modify your $PATH variable using the following command:

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

GUI apps can modify the $PATH as follows:

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

Either of these approaches are useful because /usr/local is considered a “safe” location on systems which have SIP enabled, they avoid potential conflicts with the version of Ruby included by Apple, and it keeps Jekyll and its dependencies in a sandboxed environment. This also has the added benefit of not requiring sudo when you want to add or remove a gem.

Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)

This error can occur during the installation of jekyll-coffeescript when you don’t have a proper JavaScript runtime. To solve this, either install execjs and therubyracer gems, or install nodejs . Check out issue #2327 for more info.

Problems running Jekyll

macOS

Jekyll is compatible with macOS with ARM64 architecture. However, bundle exec jekyll serve may fail with older version ffi .

You may need to run bundle update or update ffi to at least 1.14.2 manually.

Debian or Ubuntu

On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in order to have the jekyll executable be available in your Terminal.

Base-URL Problems

If you are using base-url option like:

jekyll serve 
--baseurl
 '/blog'

… then make sure that you access the site at:

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

It won’t work to just access:

http://localhost:4000/blog

Configuration problems

The order of precedence for conflicting configuration settings is as follows:

  1. Command-line flags
  2. Configuration file settings
  3. Defaults

That is: defaults are overridden by options specified in _config.yml , and flags specified at the command-line will override all other settings specified elsewhere.

Note: From v3.3.0 onward, Jekyll does not process node_modules and certain subdirectories within vendor , by default. But, by having an exclude: array defined explicitly in the config file overrides this default setting, which results in some users to encounter an error in building the site, with the following error message:

    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.

Adding vendor/bundle to the exclude: list will solve this problem but will lead to having other sub-directories under /vendor/ (and also /node_modules/ , if present) be processed to the destination folder _site .

The proper solution is to incorporate the default setting for exclude: rather than override it completely:

For versions up to v3.4.3 , the exclude: setting must look like following:

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

From v3.5 onward, Gemfile and Gemfile.lock are also excluded by default. So, in most cases there is no need to define another exclude: array in the config file. So an existing definition can either be modified as above, or removed completely, or commented out to enable easy edits in future.

Markup Problems

The various markup engines that Jekyll uses may have some issues. This page will document them to help others who may run into the same problems.

Liquid

Liquid version 2.0 seems to break the use of {{ in templates. Unlike previous versions, using {{ in 2.0 triggers the following error:

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

Excerpts

Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause strange errors where references don’t exist or a tag hasn’t been closed. If you run into these errors, try setting excerpt_separator: "" in your _config.yml , or set it to some nonsense string.

Production Problems

If you run into an issue that a static file can’t be found in your production environment during build since v3.2.0 you should set your environment to production . The issue is caused by trying to copy a non-existing symlink.

Please report issues you encounter!

If you come across a bug, please create an issue on GitHub describing the problem and any workarounds you find so we can document it here for others.

Proudly hosted by GitHub • Social coding

Jekyll is funded thanks to its sponsors!

- "漢字路" 한글한자자동변환 서비스는 교육부 고전문헌국역지원사업의 지원으로 구축되었습니다.
- "漢字路" 한글한자자동변환 서비스는 전통문화연구회 "울산대학교한국어처리연구실 옥철영(IT융합전공)교수팀"에서 개발한 한글한자자동변환기를 바탕하여 지속적으로 공동 연구 개발하고 있는 서비스입니다.
- 현재 고유명사(인명, 지명등)을 비롯한 여러 변환오류가 있으며 이를 해결하고자 많은 연구 개발을 진행하고자 하고 있습니다. 이를 인지하시고 다른 곳에서 인용시 한자 변환 결과를 한번 더 검토하시고 사용해 주시기 바랍니다.
- 변환오류 및 건의,문의사항은 juntong@juntong.or.kr로 메일로 보내주시면 감사하겠습니다. .
Copyright ⓒ 2020 By '전통문화연구회(傳統文化硏究會)' All Rights reserved.
 한국   대만   중국   일본