Configuration Options

The tables below list the available settings for Jekyll, and the various options (specified in the configuration file) and flags (specified on the command-line) that control them.

Global Configuration

Setting Options and Flags

Site Source

Change the directory where Jekyll will read files

source: DIR

-s, --source DIR

Site Destination

Change the directory where Jekyll will write files

destination: DIR

-d, --destination DIR

Safe

Disable non-whitelisted plugins, caching to disk, and ignore symbolic links.

safe: BOOL

--safe

Disable Disk Cache 4.1.0

Disable caching of content to disk in order to skip creating a .jekyll-cache or similar directory at the source to avoid interference with virtual environments and third-party directory watchers. Caching to disk is always disabled in safe mode.

disable_disk_cache: BOOL

--disable-disk-cache

Ignore theme configuration 4.1.0

Jekyll 4.0 started allowing themes to bundle a _config.yml to simplify theme-onboarding for new users. In the unfortunate situation that importing a bundled theme configuration messes up the merged site-configuration, the user can configure Jekyll to not import the theme-config entirely.

ignore_theme_config: BOOL

Exclude

Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory.

exclude: [DIR, FILE, ...]

Include

Force inclusion of directories and/or files in the conversion. .htaccess is a good example since dotfiles are excluded by default.

include: [DIR, FILE, ...]

Keep files

When clobbering the site destination, keep the selected files. Useful for files that are not generated by jekyll; e.g. files or assets that are generated by your build tool. The paths are relative to the destination.

keep_files: [DIR, FILE, ...]

Time Zone

Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the IANA Time Zone Database is valid, e.g. America/New_York. A list of all available values can be found here. When serving on a local machine, the default time zone is set by your operating system. But when served on a remote host/server, the default time zone depends on the server's setting or location.

timezone: TIMEZONE

Encoding

Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is utf-8 starting in 2.0.0, and nil before 2.0.0, which will yield the Ruby default of ASCII-8BIT. Available encodings can be shown by the command ruby -e 'puts Encoding::list.join("\n")'.

encoding: ENCODING

Defaults

Set defaults for front matter variables.

see below
Destination folders are cleaned on site builds

The contents of <destination> are automatically cleaned, by default, when the site is built. Files or folders that are not created by your site will be removed. Some files could be retained by specifying them within the <keep_files> configuration directive.

Do not use an important location for <destination>; instead, use it as a staging area and copy files from there to your web server.

Build Command Options

Setting Options and Flags

Regeneration

Enable auto-regeneration of the site when files are modified.

-w, --[no-]watch

Configuration

Specify config files instead of using _config.yml automatically. Settings in later files override settings in earlier files.

--config FILE1[,FILE2,...]

Plugins

Specify plugin directories instead of using _plugins/ automatically.

plugins_dir: [ DIR1,... ]

-p, --plugins DIR1[,DIR2,...]

Layouts

Specify layout directory instead of using _layouts/ automatically.

layout_dir: DIR

--layouts DIR

Drafts

Process and render draft posts.

show_drafts: BOOL

-D, --drafts

Environment

Use a specific environment value in the build.

JEKYLL_ENV=production

Future

Publish posts or collection documents with a future date.

future: BOOL

--future

Unpublished

Render posts that were marked as unpublished.

unpublished: BOOL

--unpublished

LSI

Produce an index for related posts. Requires the classifier-reborn plugin.

lsi: BOOL

--lsi

Limit Posts

Limit the number of posts to parse and publish.

limit_posts: NUM

--limit_posts NUM

Force polling

Force watch to use polling.

force_polling: BOOL

--force_polling

Verbose output

Print verbose output.

-V, --verbose

Silence Output

Silence the normal output from Jekyll during a build.

-q, --quiet

Incremental build

Enable the experimental incremental build feature. Incremental build only re-builds posts and pages that have changed, resulting in significant performance improvements for large sites, but may also break site generation in certain cases.

incremental: BOOL

-I, --incremental

Liquid profiler

Generate a Liquid rendering profile to help you identify performance bottlenecks.

profile: BOOL

--profile

Strict Front Matter

Cause a build to fail if there is a YAML syntax error in a page's front matter.

strict_front_matter: BOOL

--strict_front_matter

Base URL

Serve the website from the given base URL.

baseurl: URL

-b, --baseurl URL

Trace

Show the full backtrace when an error occurs.

-t, --trace

Serve Command Options

In addition to the options below, the serve sub-command can accept any of the options for the build sub-command, which are then applied to the site build which occurs right before your site is served.

Setting Options and Flags

Local Server Port

Listen on the given port.

port: PORT

-P, --port PORT

Local Server Hostname

Listen at the given hostname.

host: HOSTNAME

-H, --host HOSTNAME

Live Reload

Reload a page automatically on the browser when its content is edited.

livereload: BOOL

-l, --livereload

Live Reload Ignore

File glob patterns for LiveReload to ignore.

livereload_ignore: [ GLOB1,... ]

--livereload-ignore GLOB1[,GLOB2,...]

Live Reload Min/Max Delay

Minimum/Maximum delay before automatically reloading page.

livereload_min_delay: SECONDS
livereload_max_delay: SECONDS

--livereload-min-delay SECONDS
--livereload-max-delay SECONDS

Live Reload Port

Port for LiveReload to listen on.

--livereload-port PORT

Open URL

Open the site's URL in the browser.

open_url: BOOL

-o, --open-url

Detach

Detach the server from the terminal.

detach: BOOL

-B, --detach

Skips the initial site build

Skips the initial site build which occurs before the server is started.

skip_initial_build: BOOL

--skip-initial-build

Show Directory Listing

Show a directory listing instead of loading your index file.

show_dir_listing: BOOL

--show-dir-listing

X.509 (SSL) Private Key

SSL Private Key, stored or symlinked in the site source.

--ssl-key

X.509 (SSL) Certificate

SSL Public certificate, stored or symlinked in the site source.

--ssl-cert
Do not use tabs in configuration files

This will either lead to parsing errors, or Jekyll will revert to the default settings. Use spaces instead.

© 2020 Jekyll Core Team and contributors
Licensed under the MIT license.
https://jekyllrb.com/docs/configuration/options/