github/jekyll
1
1
Fork 0
mirror of https://github.com/jekyll/jekyll.git synced 2026-02-12 15:45:21 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
fb39b41ffb4c596e31cdc6f11d6e58bda250403d
jekyll/site/docs/configuration.md
Parker Moore 6bd07501e8 Merge branch 'frontmatter-defaults' of git://github.com/maul-esel/jekyll into maul-esel-frontmatter-defaults 
* 'frontmatter-defaults' of git://github.com/maul-esel/jekyll:
  move self.type to convertible
  oops, fix minor indentation quirk
  document frontmatter defaults precedence
  adjust frontmatter defaults precedence handling
  change cucumber feature to test for precedence too
  fix frontmatter defaults for custom paths
  more robust cucumber features
  fix slash handling for paths
  move cucumber features to own file
  fix minor docs quirk
  improve path checking, now using Pathname instead of regex
  Add site documentation for the new feature
  add inline code docs
  improve validation code
  fix for Ruby 1.8
  Add basic cucumber features for frontmatter defaults
  Retrieve frontmatter defaults when retrieved internally
  make frontmatter defaults available to liquid
  add a class `FrontmatterDefaults` for handling of frontmatter defaults
  Add a method to retrieve type to post, page and draft

Conflicts:
	lib/jekyll.rb
	lib/jekyll/convertible.rb
	lib/jekyll/core_ext.rb
	lib/jekyll/page.rb
	lib/jekyll/post.rb
2014-04-04 15:32:27 -04:00

449 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
layout: docs
title: Configuration
prev_section: structure
next_section: frontmatter
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>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 frontmatter">YAML frontmatter</a>
variables.
</p>
</td>
<td class='align-center'>
<p>see <a href="#frontmatter_defaults" title="details">below</a></p>
</td>
</tr>
</tbody>
</table>
</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, --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="flag">--drafts</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>
</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>
</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>
## Frontmatter defaults
You can set default values for your [YAML frontmatter](../frontmatter/) variables
in your configuration. This way, you can for example set default layouts or define
defaults for your custom variables. Of course, any variable actually specified in
the front matter overrides the defaults.
All defaults go under the `defaults` key, which holds a list of scope-values combinations ("default sets").
The `scope` key defines for which files the defaults apply, limiting them by their `path` and
optionally by their `type` (`page`, `post` or `draft`). The `values` key holds the actual list of defaults.
For example:
{% highlight yaml %}
defaults:
-
scope:
path: "" # empty string for all files
values:
layout: "my-site"
-
scope:
path: "about/blog"
type: "post"
values:
layout: "meta-blog" # overrides previous default layout
author: "Dr. Hyde"
{% endhighlight %}
With these defaults, all pages and posts would default to the `my-site` layout except for the posts under `about/blog`,
who would default to the `meta-blog` layout and also have the `page.author` [liquid variable](../variables/) set to `Dr. Hyde` by default.
### Precedence
You can have multiple sets of frontmatter defaults that specify defaults for the same setting. In this case, for each page or post,
the default set with the more specific scope takes precedence. This way, you can specify defaults for a path like `/site/blog` that would
override any defaults for `/site`. Also, if the paths are equal, a scope with a specified type is more specific. If two sets are equally
specific, the bottom-most takes precedence.
## Default Configuration
Jekyll runs with the following configuration options by default. Unless
alternative settings for these options are explicitly specified in the
configuration file or on the command-line, Jekyll will run using these options.
<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 %}
source: .
destination: ./_site
plugins: ./_plugins
layouts: ./_layouts
include: ['.htaccess']
exclude: []
keep_files: ['.git','.svn']
gems: []
timezone: nil
encoding: nil
future: true
show_drafts: nil
limit_posts: 0
highlighter: pygments
relative_permalinks: true
permalink: date
paginate_path: 'page:num'
paginate: nil
markdown: kramdown
markdown_ext: markdown,mkdown,mkdn,mkd,md
textile_ext: textile
excerpt_separator: "\n\n"
safe: false
watch: false # deprecated
server: false # deprecated
host: 0.0.0.0
port: 4000
baseurl: /
url: http://localhost:4000
lsi: false
maruku:
use_tex: false
use_divs: false
png_engine: blahtex
png_dir: images/latex
png_url: /images/latex
fenced_code_blocks: true
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
use_coderay: false
coderay:
coderay_wrap: div
coderay_line_numbers: inline
coderay_line_numbers_start: 1
coderay_tab_width: 4
coderay_bold_every: 10
coderay_css: style
redcloth:
hard_breaks: true
{% endhighlight %}
<div class="note unreleased">
<h5>Kramdown as the default is currently unreleased.</h5>
<p>
In the latest development releases, we've deprecated Maruku and will default to
Kramdown instead of Maruku. All versions below this will use Maruku as the
default.
</p>
</div>
## 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 v2.2.x, and extensions like `footnotes` and `highlight` weren't added until after version 3.0.0. The most commonly used extensions are:
- `tables`
- `no_intra_emphasis`
- `autolink`
[redcarpet_extensions]: https://github.com/vmg/redcarpet/blob/v2.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
Reference in New Issue View Git Blame Copy Permalink