Reorganize and update default configuration settings. #2456.

lib/jekyll/configuration.rb

@@ -6,47 +6,55 @@ module Jekyll
     # Default options. Overridden by values in _config.yml.
     # Strings rather than symbols are used for compatibility with YAML.
     DEFAULTS = {
+      # Where things are
       'source'        => Dir.pwd,
       'destination'   => File.join(Dir.pwd, '_site'),
       'plugins'       => '_plugins',
       'layouts'       => '_layouts',
       'data_source'   =>  '_data',
-      'keep_files'    => ['.git','.svn'],
-      'gems'          => [],
       'collections'   => nil,
 
-      'timezone'      => nil,           # use the local timezone
+      # Handling Reading
-
-      'encoding'      => 'utf-8',       # always use utf-8 encoding. NEVER FORGET
-
       'safe'          => false,
-      'detach'        => false,          # default to not detaching the server
-      'show_drafts'   => nil,
-      'limit_posts'   => 0,
-      'lsi'           => false,
-      'future'        => true,           # remove and make true just default
-      'unpublished'   => false,
-
-      'relative_permalinks' => false,
-
-      'markdown'      => 'kramdown',
-      'highlighter'   => 'pygments',
-      'permalink'     => 'date',
-      'baseurl'       => '',
       'include'       => ['.htaccess'],
       'exclude'       => [],
-      'paginate_path' => '/page:num',
+      'keep_files'    => ['.git','.svn'],
-
+      'encoding'      => 'utf-8',
       'markdown_ext'  => 'markdown,mkdown,mkdn,mkd,md',
       'textile_ext'   => 'textile',
 
-      'quiet'         => false,
+      # Filtering Content
-      'port'          => '4000',
+      'show_drafts'   => nil,
-      'host'          => '0.0.0.0',
+      'limit_posts'   => 0,
+      'future'        => true,           # remove and make true just default
+      'unpublished'   => false,
 
+      # Plugins
+      'whitelist'     => [],
+      'gems'          => [],
+
+      # Conversion
+      'markdown'      => 'kramdown',
+      'highlighter'   => 'pygments',
+      'lsi'           => false,
       'excerpt_separator' => "\n\n",
 
-      'defaults'     => [],
+      # Serving
+      'detach'        => false,          # default to not detaching the server
+      'port'          => '4000',
+      'host'          => '0.0.0.0',
+      'baseurl'       => '',
+
+      # Backwards-compatibility options
+      'relative_permalinks' => false,
+
+      # Output Configuration
+      'permalink'     => 'date',
+      'paginate_path' => '/page:num',
+      'timezone'      => nil,           # use the local timezone
+
+      'quiet'         => false,
+      'defaults'      => [],
 
       'maruku' => {
         'use_tex'    => false,

site/_docs/configuration.md

@@ -400,42 +400,57 @@ configuration file or on the command-line, Jekyll will run using these options.
 </div>
 
 {% highlight yaml %}
+# Where things are
 source:      .
 destination: ./_site
 plugins:     ./_plugins
 layouts:     ./_layouts
-include:     ['.htaccess']
+data_source: ./_data
-exclude:     []
+collections: nil
-keep_files:  ['.git','.svn']
-gems:        []
-timezone:    nil
-encoding:    nil
 
-future:      true
+# Handling Reading
-show_drafts: false
+safe:         false
+include:      [".htaccess"]
+exclude:      []
+keep_files:   [".git", ".svn"]
+encoding:     "utf-8"
+markdown_ext: "markdown,mkdown,mkdn,mkd,md"
+textile_ext:  "textile"
+
+# Filtering Content
+show_drafts: nil
 limit_posts: 0
+future:      true
+unpublished: false
+
+# Plugins
+whitelist: []
+gems:      []
+
+# Conversion
+markdown:    kramdown
 highlighter: pygments
-
+lsi:         false
-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
+# Serving
-watch:       false    # deprecated
+detach:  false
-server:      false    # deprecated
+port:    4000
-host:        0.0.0.0
+host:    0.0.0.0
-port:        4000
+baseurl: "" # does not include hostname
-baseurl:     ""
-lsi:         false
 
+# Backwards-compatibility
+relative_permalinks: false
+
+# Outputting
+permalink:     date
+paginate_path: /page:num
+timezone:      nil
+
+quiet:    false
+defaults: []
+
+# Markdown Processors
 maruku:
   use_tex:    false
   use_divs:   false
@@ -451,20 +466,20 @@ redcarpet:
   extensions: []
 
 kramdown:
-  auto_ids: true
+  auto_ids:      true
-  footnote_nr: 1
+  footnote_nr:   1
   entity_output: as_char
-  toc_levels: 1..6
+  toc_levels:    1..6
-  smart_quotes: lsquo,rsquo,ldquo,rdquo
+  smart_quotes:  lsquo,rsquo,ldquo,rdquo
-  use_coderay: false
+  use_coderay:   false
 
   coderay:
-    coderay_wrap: div
+    coderay_wrap:              div
-    coderay_line_numbers: inline
+    coderay_line_numbers:      inline
-    coderay_line_numbers_start: 1
+    coderay_line_number_start: 1
-    coderay_tab_width: 4
+    coderay_tab_width:         4
-    coderay_bold_every: 10
+    coderay_bold_every:        10
-    coderay_css: style
+    coderay_css:               style
 
 redcloth:
   hard_breaks: true