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 options (specified in the configuration file) and flags (specified on the command-line) that control them.

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 custom plugins, and ignore symbolic links.	safe: BOOL --safe
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, ...]
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. The default is the local time zone, as set by your operating system.	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 YAML frontmatter variables.	see below

Build Command Options

Setting	Options and Flags
Regeneration Enable auto-regeneration of the site when files are modified.	-w, --watch
Configuration Specify config files instead of using _config.yml automatically. Settings in later files override settings in earlier files.	--config FILE1[,FILE2,...]
Drafts Process and render draft posts.	--drafts
Future Publish posts with a future date.	future: BOOL --future
LSI Produce an index for related posts.	lsi: BOOL --lsi
Limit Posts Limit the number of posts to parse and publish.	limit_posts: NUM --limit_posts NUM

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 --port PORT
Local Server Hostname Listen at the given hostname.	host: HOSTNAME --host HOSTNAME
Base URL Serve the website from the given base URL	baseurl: URL --baseurl URL
Detach Detach the server from the terminal	detach: BOOL -B, --detach

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.

Frontmatter defaults

You can set default values for your YAML 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:

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"

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 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.

There are two unsupported kramdown options

Please note that both remove_block_html_tags and remove_span_html_tags are currently unsupported in Jekyll due to the fact that they are not included within the kramdown HTML converter.

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

Kramdown as the default is currently unreleased.

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.

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. 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

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

Back

Next