Wiki


Jekyll — Config

For site wide configurations, Jekyll uses _config.yml file, which should be located at the root of Jekyll website. To apply changes, can have to restart Jekyll server after editing the file, if it’s already running, because Jekyll only parse the configuration file on startup.

Options

Configuration options can be listed into this file so that Jekyll automatically parse those options without command line argument. Following is the list of available configuration options.

source

This option can be used to provide alternative source directory for Jekyll to look for files. The path to the directory can be relative to the _config.yml file. This can also be achieved by using the command line argument --source DIR or -s DIR.

destination

This option is similar to source, but for destination of generated HTML files. The path to the directory can be relative to the _config.yml file. This can also be achieved by using the command line argument --destination DIR or -d DIR.

safe

This option takes true or false as arguments which turns safe mode on and off respectively. By default safe mode is turned off. Safe mode disables all the plugins. This can also be achieved by using the command line argument --safe. Github Pages is known to use this option for all the sites.

exclude

This option takes an array of file/directory names as arguments, which are excluded from conversion. The file and directory paths are relative to the root of Jekyll site.

include

This option is opposite of exclude, which include its arguments forcefully which are excluded by default, like dotfiles.

timezone

This option sets the TZ environment variable in Ruby which is used to handle time and date. Any entry from the IANA Time Zone Database is valid. A list of all values can be found here.

Server

Jekyll is commonly used as static site generator, but it also comes with a simple web server, WEBrick, which can be directly used to serve the website. Following are the options to configure server:

port

This option is used to set the port which is used to serve the website. The default value is 4000. This can alternatively be achieved using the command line argument --port PORT for the serve sub-command.

host

This option is used to set the hostname or IP address which is used to serve the website. This default value is 127.0.0.1, which serves the website locally. To serve website using all interfaces 0.0.0.0 can be used. This can also be achieved using the command line argument --host HOSTNAME for the serve sub-command.

baseurl

This option sets the baseurl to serve the website from. The command line argument alternative for it is --baseurl URL.

detach

This option takes true or false as its arguments. The default is false so the process remains attached to the shell after executing the serve sub-command. If set to true the serve detaches itself from the shell and runs in background.

Custom headers can also be provided to the WEBrick server by adding the following section in _config.yml file.

webrick:
  headers:
    My-Header: My-Value
    My-Other-Header: My-Other-Value

Variable

The _config.yml file can contain global variables which are accessible by any template file site-wide. These variables are available under site class.

Declaring Variable

var: test

Using Variable

{{ site.var }}

See Also