Configuration
Jekyll gives you a lot of flexibility to customize how it builds your site. These options can either be specified in a _config.yml or _config.tomlfile placed in your site’s root directory, or can be specified as flags for the jekyll executable in the terminal.
- Configuration Options
- Default Configuration
- Front Matter Defaults
- Environments
- Markdown Options
- Liquid Options
- Sass/SCSS Options
- Webrick Options
- Incremental Regeneration
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 ConfigurationPermalink
| 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. This configuration option supports Ruby’s File.fnmatch filename globbing patterns to match multiple entries to exclude. For example, you can exclude multiple README.md files in your source tree from being included in your site by specifying the following exclude option entries: ["README.md", "**/README.md"]. In Jekyll 3, the exclude configuration option replaces the default exclusion list. In Jekyll 4, user-provided entries get added to the default exclusion list instead and the includeoption can be used to override the default exclusion list entries. The default exclusions are found in _config.ymlas created by jekyll new: - .sass-cache/- .jekyll-cache/- gemfiles/- Gemfile- Gemfile.lock- node_modules/- vendor/bundle/- vendor/cache/- vendor/gems/- vendor/ruby/ |
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. This configuration option supports Ruby’s File.fnmatch filename globbing patterns to match multiple entries to include, refer the exclude configuration option for more information. With Jekyll 4, the include configuration option entries override the exclude option entries. |
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-8starting 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 OptionsPermalink
| 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. |
layouts_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. |
verbose: BOOL-V, --verbose |
| Silence output Silence the normal output from Jekyll during a build. |
quiet: BOOL-q, --quiet |
| Log level Specify a log level among debug, info, warn, or error. |
JEKYLL_LOG_LEVEL=info |
| Incremental build Enable the experimental incremental buildfeature. 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 |
| Disable bundle require Disables the need to require gems in :jekyll_plugins Gemfile |
JEKYLL_NO_BUNDLER_REQUIRE=true |
| 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 |
| Web Domain URL The canonical URL of the root of your production deploy, composed of the following components: • Protocol scheme (e.g. http://) • Hostname or IP address (e.g. example.org) • (Optional) The port number of the server, prefixed with a colon (e.g. :8080) The value of this configuration option should NOT have a trailing slash. It will be appended with the baseurl to form the full URL to your Jekyll site when using the Liquid filter absolute_url. NOTE: This setting is automatically configured to the localhost URL when the jekyll servecommand is invoked. |
url: SCHEME://HOST[:PORT] |
| Base URL Serve the website from the given base URL (the path between web-server or domain root and your landing page). |
baseurl: /PATH/TO/SITE-b, --baseurl /PATH/TO/SITE |
| Trace Show the full backtrace when an error occurs. |
-t, --trace |
Serve Command OptionsPermalink
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. The default is 4000. |
port: PORT-P, --port PORT |
| Local server hostname Listen at the given hostname. The default is localhost. |
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. Ensure that patterns are quoted when passed via the command-line to deter your shell from expanding them. Note: The given glob patterns are matched against the relative_pathattribute of the processed resource. In the event Jekyll reloads a _relative_path_matching the pattern in spite of being quoted, try listing the pattern(s) under the config file option key. |
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. Ability to override via config file introduced in 4.4.0. |
livereload_port: PORT--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.