---
layout: docs
title: Configuration
permalink: /docs/configuration/
---
Jekyll allows you to concoct your sites in any way you can dream up, and it’s
thanks to the powerful and flexible configuration options that this is possible.
These options can either be specified in a `_config.yml` file placed in your
site’s root directory, or can be specified as flags for the `jekyll` executable
in the terminal.
## Configuration Settings
### Global Configuration
The table below lists the available settings for Jekyll, and the various <code
class="option">options</code> (specified in the configuration file) and <code
class="flag">flags</code> (specified on the command-line) that control them.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th>
<span class="option">Options</span> and <span class="flag">Flags</span>
</th>
</tr>
</thead>
<tbody>
<tr class="setting">
<td>
<p class="name"><strong>Site Source</strong></p>
<p class="description">Change the directory where Jekyll will read files</p>
</td>
<td class="align-center">
<p><code class="option">source: DIR</code></p>
<p><code class="flag">-s, --source DIR</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Site Destination</strong></p>
<p class="description">Change the directory where Jekyll will write files</p>
</td>
<td class="align-center">
<p><code class="option">destination: DIR</code></p>
<p><code class="flag">-d, --destination DIR</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Safe</strong></p>
<p class="description">Disable <a href="../plugins/">custom plugins, and ignore symbolic links</a>.</p>
</td>
<td class="align-center">
<p><code class="option">safe: BOOL</code></p>
<p><code class="flag">--safe</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Exclude</strong></p>
<p class="description">
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.
</p>
</td>
<td class="align-center">
<p><code class="option">exclude: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Include</strong></p>
<p class="description">
Force inclusion of directories and/or files in the conversion.
<code>.htaccess</code> is a good example since dotfiles are excluded
by default.
</p>
</td>
<td class="align-center">
<p><code class="option">include: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Keep files</strong></p>
<p class="description">
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 <code>destination</code>.
</p>
</td>
<td class="align-center">
<p><code class="option">keep_files: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Time Zone</strong></p>
<p class="description">
Set the time zone for site generation. This sets the <code>TZ</code>
environment variable, which Ruby uses to handle time and date
creation and manipulation. Any entry from the
<a href="http://en.wikipedia.org/wiki/Tz_database">IANA Time Zone
Database</a> is valid, e.g. <code>America/New_York</code>. A list of all
available values can be found <a href="http://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
here</a>. The default is the local time zone, as set by your operating system.
</p>
</td>
<td class="align-center">
<p><code class="option">timezone: TIMEZONE</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Encoding</strong></p>
<p class="description">
Set the encoding of files by name (only available for Ruby
1.9 or later).
The default value is <code>utf-8</code> starting in 2.0.0,
and <code>nil</code> before 2.0.0, which will yield the Ruby
default of <code>ASCII-8BIT</code>.
Available encodings can be shown by the
command <code>ruby -e 'puts Encoding::list.join("\n")'</code>.
</p>
</td>
<td class="align-center">
<p><code class="option">encoding: ENCODING</code></p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Defaults</strong></p>
<p class='description'>
Set defaults for <a href="../frontmatter/" title="YAML Front Matter">YAML Front Matter</a>
variables.
</p>
</td>
<td class='align-center'>
<p>see <a href="#front-matter-defaults" title="details">below</a></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note warning">
<h5>Destination folders are cleaned on site builds</h5>
<p>
The contents of <code><destination></code> 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 <code><keep_files></code> configuration directive.
</p>
<p>
Do not use an important location for <code><destination></code>; instead, use it as
a staging area and copy files from there to your web server.
</p>
</div>
### Build Command Options
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class="setting">
<td>
<p class="name"><strong>Regeneration</strong></p>
<p class="description">Enable auto-regeneration of the site when files are modified.</p>
</td>
<td class="align-center">
<p><code class="flag">-w, --[no-]watch</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Configuration</strong></p>
<p class="description">Specify config files instead of using <code>_config.yml</code> automatically. Settings in later files override settings in earlier files.</p>
</td>
<td class="align-center">
<p><code class="flag">--config FILE1[,FILE2,...]</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Drafts</strong></p>
<p class="description">Process and render draft posts.</p>
</td>
<td class="align-center">
<p><code class="option">show_drafts: BOOL</code></p>
<p><code class="flag">--drafts</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Environment</strong></p>
<p class="description">Use a specific environment value in the build.</p>
</td>
<td class="align-center">
<p><code class="flag">JEKYLL_ENV=production</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Future</strong></p>
<p class="description">Publish posts with a future date.</p>
</td>
<td class="align-center">
<p><code class="option">future: BOOL</code></p>
<p><code class="flag">--future</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>LSI</strong></p>
<p class="description">Produce an index for related posts.</p>
</td>
<td class="align-center">
<p><code class="option">lsi: BOOL</code></p>
<p><code class="flag">--lsi</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Limit Posts</strong></p>
<p class="description">Limit the number of posts to parse and publish.</p>
</td>
<td class="align-center">
<p><code class="option">limit_posts: NUM</code></p>
<p><code class="flag">--limit_posts NUM</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Force polling</strong></p>
<p class="description">Force watch to use polling.</p>
</td>
<td class="align-center">
<p><code class="flag">--force_polling</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Verbose output</strong></p>
<p class="description">Print verbose output.</p>
</td>
<td class="align-center">
<p><code class="flag">-V, --verbose</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Silence Output</strong></p>
<p class="description">Silence the normal output from Jekyll
during a build</p>
</td>
<td class="align-center">
<p><code class="flag">-q, --quiet</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Incremental build</strong></p>
<p class="description">
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.
</p>
</td>
<td class="align-center">
<p><code class="option">incremental: BOOL</code></p>
<p><code class="flag">-I, --incremental</code></p>
</td>
</tr>
</tbody>
</table>
</div>
### 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.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class="setting">
<td>
<p class="name"><strong>Local Server Port</strong></p>
<p class="description">Listen on the given port.</p>
</td>
<td class="align-center">
<p><code class="option">port: PORT</code></p>
<p><code class="flag">--port PORT</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Local Server Hostname</strong></p>
<p class="description">Listen at the given hostname.</p>
</td>
<td class="align-center">
<p><code class="option">host: HOSTNAME</code></p>
<p><code class="flag">--host HOSTNAME</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Base URL</strong></p>
<p class="description">Serve the website from the given base URL</p>
</td>
<td class="align-center">
<p><code class="option">baseurl: URL</code></p>
<p><code class="flag">--baseurl URL</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Detach</strong></p>
<p class="description">Detach the server from the terminal</p>
</td>
<td class="align-center">
<p><code class="option">detach: BOOL</code></p>
<p><code class="flag">-B, --detach</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>Skips the initial site build.</strong></p>
<p class="description">Skips the initial site build which occurs before the server is started.</p>
</td>
<td class="align-center">
<p><code class="flag">--skip-initial-build</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>X.509 (SSL) Private Key</strong></p>
<p class="description">SSL Private Key.</p>
</td>
<td class="align-center">
<p><code class="flag">--ssl-key</code></p>
</td>
</tr>
<tr class="setting">
<td>
<p class="name"><strong>X.509 (SSL) Certificate</strong></p>
<p class="description">SSL Public certificate.</p>
</td>
<td class="align-center">
<p><code class="flag">--ssl-cert</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note warning">
<h5>Do not use tabs in configuration files</h5>
<p>
This will either lead to parsing errors, or Jekyll will revert to the
default settings. Use spaces instead.
</p>
</div>
## Custom WEBRick Headers
You can provide custom headers for your site by adding them to `_config.yml`
{% highlight yaml %}
# File: _config.yml
webrick:
headers:
My-Header: My-Value
My-Other-Header: My-Other-Value
{% endhighlight %}
### Defaults
We only provide one default and that's a Content-Type header that disables
caching in development so that you don't have to fight with Chrome's aggressive
caching when you are in development mode.
## Specifying a Jekyll environment at build time
In the build (or serve) arguments, you can specify a Jekyll environment and value. The build will then apply this value in any conditional statements in your content.
For example, suppose you set this conditional statement in your code:
{% highlight liquid %}
{% raw %}
{% if jekyll.environment == "production" %}
{% include disqus.html %}
{% endif %}
{% endraw %}
{% endhighlight %}
When you build your Jekyll site, the content inside the `if` statement won't be run unless you also specify a `production` environment in the build command, like this:
{% highlight sh %}
JEKYLL_ENV=production jekyll build
{% endhighlight %}
Specifying an environment value allows you to make certain content available only within specific environments.
The default value for `JEKYLL_ENV` is `development`. Therefore if you omit `JEKYLL_ENV` from the build arguments, the default value will be `JEKYLL_ENV=development`. Any content inside `{% raw %}{% if jekyll.environment == "development" %}{% endraw %}` tags will automatically appear in the build.
Your environment values can be anything you want (not just `development` or `production`). Some elements you might want to hide in development environments include Disqus comment forms or Google Analytics. Conversely, you might want to expose an "Edit me in GitHub" button in a development environment but not include it in production environments.
By specifying the option in the build command, you avoid having to change values in your configuration files when moving from one environment to another.
## Front Matter defaults
Using [YAML Front Matter](../frontmatter/) is one way that you can specify configuration in the pages and posts for your site. Setting things like a default layout, or customizing the title, or specifying a more precise date/time for the post can all be added to your page or post front matter.
Often times, you will find that you are repeating a lot of configuration options. Setting the same layout in each file, adding the same category - or categories - to a post, etc. You can even add custom variables like author names, which might be the same for the majority of posts on your blog.
Instead of repeating this configuration each time you create a new post or page, Jekyll provides a way to set these defaults in the site configuration. To do this, you can specify site-wide defaults using the `defaults` key in the `_config.yml` file in your projects root directory.
The `defaults` key holds an array of scope/values pairs that define what defaults should be set for a particular file path, and optionally, a file type in that path.
Let's say that you want to add a default layout to all pages and posts in your site. You would add this to your `_config.yml` file:
{% highlight yaml %}
defaults:
-
scope:
path: "" # an empty string here means all files in the project
values:
layout: "default"
{% endhighlight %}
Here, we are scoping the `values` to any file that exists in the scopes path. Since the path is set as an empty string, it will apply to **all files** in your project. You probably don't want to set a layout on every file in your project - like css files, for example - so you can also specify a `type` value under the `scope` key.
{% highlight yaml %}
defaults:
-
scope:
path: "" # an empty string here means all files in the project
type: "posts" # previously `post` in Jekyll 2.2.
values:
layout: "default"
{% endhighlight %}
Now, this will only set the layout for files where the type is `posts`.
The different types that are available to you are `pages`, `posts`, `drafts` or any collection in your site. While `type` is optional, you must specify a value for `path` when creating a `scope/values` pair.
As mentioned earlier, you can set multiple scope/values pairs for `defaults`.
{% highlight yaml %}
defaults:
-
scope:
path: ""
type: "posts"
values:
layout: "my-site"
-
scope:
path: "projects"
type: "pages" # previously `page` in Jekyll 2.2.
values:
layout: "project" # overrides previous default layout
author: "Mr. Hyde"
{% endhighlight %}
With these defaults, all posts would use the `my-site` layout. Any html files that exist in the `projects/` folder will use the `project` layout, if it exists. Those files will also have the `page.author` [liquid variable](../variables/) set to `Mr. Hyde` as well as have the category for the page set to `project`.
{% highlight yaml %}
collections:
- my_collection:
output: true
defaults:
-
scope:
path: ""
type: "my_collection" # a collection in your site, in plural form
values:
layout: "default"
{% endhighlight %}
In this example, the `layout` is set to `default` inside the
[collection](../collections/) with the name `my_collection`.
### Precedence
Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.
You can see that in the second to last example above. First, we set the default layout to `my-site`. Then, using a more specific path, we set the default layout for files in the `projects/` path to `project`. This can be done with any value that you would set in the page or post front matter.
Finally, if you set defaults in the site configuration by adding a `defaults` section to your `_config.yml` file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front matter. For example:
{% highlight yaml %}
# In _config.yml
...
defaults:
-
scope:
path: "projects"
type: "pages"
values:
layout: "project"
author: "Mr. Hyde"
category: "project"
...
{% endhighlight %}
{% highlight yaml %}
# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...
{% endhighlight %}
The `projects/foo_project.md` would have the `layout` set to `foobar` instead
of `project` and the `author` set to `John Smith` instead of `Mr. Hyde` when
the site is built.
## Default Configuration
Jekyll runs with the following configuration options by default. Alternative
settings for these options can be explicitly specified in the configuration
file or on the command-line.
<div class="note warning">
<h5>There are two unsupported kramdown options</h5>
<p>
Please note that both <code>remove_block_html_tags</code> and
<code>remove_span_html_tags</code> are currently unsupported in Jekyll due
to the fact that they are not included within the kramdown HTML converter.
</p>
</div>
{% highlight yaml %}
# Where things are
source: .
destination: ./_site
plugins_dir: ./_plugins
layouts_dir: ./_layouts
data_dir: ./_data
includes_dir: ./_includes
collections: null
# Handling Reading
safe: false
include: [".htaccess"]
exclude: []
keep_files: [".git", ".svn"]
encoding: "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"
# Filtering Content
show_drafts: null
limit_posts: 0
future: false
unpublished: false
# Plugins
whitelist: []
gems: []
# Conversion
markdown: kramdown
highlighter: rouge
lsi: false
excerpt_separator: "\n\n"
incremental: false
# Serving
detach: false
port: 4000
host: 127.0.0.1
baseurl: "" # does not include hostname
# Outputting
permalink: date
paginate_path: /page:num
timezone: null
quiet: false
defaults: []
# Markdown Processors
rdiscount:
extensions: []
redcarpet:
extensions: []
kramdown:
auto_ids: true
footnote_nr: 1
entity_output: as_char
toc_levels: 1..6
smart_quotes: lsquo,rsquo,ldquo,rdquo
enable_coderay: false
coderay:
coderay_wrap: div
coderay_line_numbers: inline
coderay_line_number_start: 1
coderay_tab_width: 4
coderay_bold_every: 10
coderay_css: style
{% endhighlight %}
## Markdown Options
The various Markdown renderers supported by Jekyll sometimes have extra options
available.
### Redcarpet
Redcarpet can be configured by providing an `extensions` sub-setting, whose
value should be an array of strings. Each string should be the name of one of
the `Redcarpet::Markdown` class's extensions; if present in the array, it will
set the corresponding extension to `true`.
Jekyll handles two special Redcarpet extensions:
- `no_fenced_code_blocks` --- By default, Jekyll sets the `fenced_code_blocks`
extension (for delimiting code blocks with triple tildes or triple backticks)
to `true`, probably because GitHub's eager adoption of them is starting to make
them inescapable. Redcarpet's normal `fenced_code_blocks` extension is inert
when used with Jekyll; instead, you can use this inverted version of the
extension for disabling fenced code.
Note that you can also specify a language for highlighting after the first
delimiter:
```ruby
# ...ruby code
```
With both fenced code blocks and highlighter enabled, this will statically
highlight the code; without any syntax highlighter, it will add a
`class="LANGUAGE"` attribute to the `<code>` element, which can be used as a
hint by various JavaScript code highlighting libraries.
- `smart` --- This pseudo-extension turns on SmartyPants, which converts
straight quotes to curly quotes and runs of hyphens to em (`---`) and en (`--`) dashes.
All other extensions retain their usual names from Redcarpet, and no renderer
options aside from `smart` can be specified in Jekyll. [A list of available
extensions can be found in the Redcarpet README file.][redcarpet_extensions]
Make sure you're looking at the README for the right version of
Redcarpet: Jekyll currently uses v3.2.x. The most commonly used
extensions are:
- `tables`
- `no_intra_emphasis`
- `autolink`
[redcarpet_extensions]: https://github.com/vmg/redcarpet/blob/v3.2.2/README.markdown#and-its-like-really-simple-to-use
### Kramdown
In addition to the defaults mentioned above, you can also turn on recognition
of GitHub Flavored Markdown by passing an `input` option with a value of "GFM".
For example, in your `_config.yml`:
kramdown:
input: GFM
### Custom Markdown Processors
If you're interested in creating a custom markdown processor, you're in luck! Create a new class in the `Jekyll::Converters::Markdown` namespace:
{% highlight ruby %}
class Jekyll::Converters::Markdown::MyCustomProcessor
def initialize(config)
require 'funky_markdown'
@config = config
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install funky_markdown'
raise FatalException.new("Missing dependency: funky_markdown")
end
def convert(content)
::FunkyMarkdown.new(content).convert
end
end
{% endhighlight %}
Once you've created your class and have it properly set up either as a plugin
in the `_plugins` folder or as a gem, specify it in your `_config.yml`:
{% highlight yaml %}
markdown: MyCustomProcessor
{% endhighlight %}
## Incremental Regeneration
<div class="note warning">
<h5>Incremental regeneration is still an experimental feature</h5>
<p>
While incremental regeneration will work for the most common cases, it will
not work correctly in every scenario. Please be extremely cautious when
using the feature, and report any problems not listed below by
<a href="https://github.com/jekyll/jekyll/issues/new">opening an issue on GitHub</a>.
</p>
</div>
Incremental regeneration helps shorten build times by only generating documents
and pages that were updated since the previous build. It does this by keeping
track of both file modification times and inter-document dependencies in the
`.jekyll-metadata` file.
Under the current implementation, incremental regeneration will only generate a
document or page if either it, or one of its dependencies, is modified. Currently,
the only types of dependencies tracked are includes (using the
{% raw %}`{% include %}`{% endraw %} tag) and layouts. This means that plain
references to other documents (for example, the common case of iterating over
`site.posts` in a post listings page) will not be detected as a dependency.
To remedy some of these shortfalls, putting `regenerate: true` in the front-matter
of a document will force Jekyll to regenerate it regardless of whether it has been
modified. Note that this will generate the specified document only; references
to other documents' contents will not work since they won't be re-rendered.
Incremental regeneration can be enabled via the `--incremental` flag (`-I` for
short) from the command-line or by setting `incremental: true` in your
configuration file.