443 lines
15 KiB
Markdown
443 lines
15 KiB
Markdown
---
|
|
title: Configuration Options
|
|
permalink: "/docs/configuration/options/"
|
|
---
|
|
|
|
The tables below list 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.
|
|
|
|
### Global Configuration
|
|
|
|
<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="/docs/plugins/">custom plugins</a>, caching to disk
|
|
and ignore symbolic links.
|
|
</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>Disable Disk Cache</strong>
|
|
<span class="version-badge" title="Introduced in v4.1.0">4.1.0</span>
|
|
</p>
|
|
<p class="description">
|
|
Disable caching of content to disk in order to skip creating a
|
|
<code>.jekyll-cache</code> or similar directory at the source
|
|
to avoid interference with virtual environments and third-party
|
|
directory watchers.
|
|
Caching to disk is always disabled in <code>safe</code> mode.
|
|
</p>
|
|
</td>
|
|
<td class="align-center">
|
|
<p><code class="option">disable_disk_cache: BOOL</code></p>
|
|
<p><code class="flag">--disable-disk-cache</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="https://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="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">
|
|
here</a>. 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.
|
|
</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="/docs/front-matter/" title="front matter">front matter</a>
|
|
variables.
|
|
</p>
|
|
</td>
|
|
<td class='align-center'>
|
|
<p>see <a href="/docs/configuration/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 or collection documents 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>Unpublished</strong></p>
|
|
<p class="description">Render posts that were marked as unpublished.</p>
|
|
</td>
|
|
<td class="align-center">
|
|
<p><code class="option">unpublished: BOOL</code></p>
|
|
<p><code class="flag">--unpublished</code></p>
|
|
</td>
|
|
</tr>
|
|
<tr class="setting">
|
|
<td>
|
|
<p class="name"><strong>LSI</strong></p>
|
|
<p class="description">Produce an index for related posts. Requires the <a href="http://www.classifier-reborn.com/">classifier-reborn</a> plugin.</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="option">force_polling: BOOL</code></p>
|
|
<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>
|
|
<tr class="setting">
|
|
<td>
|
|
<p class="name"><strong>Liquid profiler</strong></p>
|
|
<p class="description">
|
|
Generate a Liquid rendering profile to help you identify performance bottlenecks.
|
|
</p>
|
|
</td>
|
|
<td class="align-center">
|
|
<p><code class="option">profile: BOOL</code></p>
|
|
<p><code class="flag">--profile</code></p>
|
|
</td>
|
|
</tr>
|
|
<tr class="setting">
|
|
<td>
|
|
<p class="name"><strong>Strict Front Matter</strong></p>
|
|
<p class="description">
|
|
Cause a build to fail if there is a YAML syntax error in a page's front matter.
|
|
</p>
|
|
</td>
|
|
<td class="align-center">
|
|
<p><code class="option">strict_front_matter: BOOL</code></p>
|
|
<p><code class="flag">--strict_front_matter</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>
|
|
</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>Live Reload</strong></p>
|
|
<p class="description">Reload a page automatically on the browser when its content is edited.</p>
|
|
</td>
|
|
<td class="align-center">
|
|
<p><code class="option">livereload: true</code></p>
|
|
<p><code class="flag">-l, --livereload</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, stored or symlinked in the site source.</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, stored or symlinked in the site source.</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>
|