Reorganize and update default configuration settings. #2456.

lib/jekyll/configuration.rb

@@ -6,46 +6,54 @@ 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",
 
+      # 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' => {

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
+collections: nil
+
+# Handling Reading
+safe:         false
+include:      [".htaccess"]
 exclude:      []
-keep_files:  ['.git','.svn']
+keep_files:   [".git", ".svn"]
-gems:        []
+encoding:     "utf-8"
-timezone:    nil
+markdown_ext: "markdown,mkdown,mkdn,mkd,md"
-encoding:    nil
+textile_ext:  "textile"
 
-future:      true
+# Filtering Content
-show_drafts: false
+show_drafts: nil
 limit_posts: 0
-highlighter: pygments
+future:      true
+unpublished: false
 
-relative_permalinks: true
+# Plugins
-
+whitelist: []
-permalink:     date
+gems:      []
-paginate_path: 'page:num'
-paginate:      nil
 
+# Conversion
 markdown:    kramdown
-markdown_ext:  markdown,mkdown,mkdn,mkd,md
+highlighter: pygments
-textile_ext:   textile
+lsi:         false
-
 excerpt_separator: "\n\n"
 
-safe:        false
+# Serving
-watch:       false    # deprecated
+detach:  false
-server:      false    # deprecated
-host:        0.0.0.0
 port:    4000
-baseurl:     ""
+host:    0.0.0.0
-lsi:         false
+baseurl: "" # does not include hostname
 
+# 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
@@ -461,7 +476,7 @@ kramdown:
   coderay:
     coderay_wrap:              div
     coderay_line_numbers:      inline
-    coderay_line_numbers_start: 1
+    coderay_line_number_start: 1
     coderay_tab_width:         4
     coderay_bold_every:        10
     coderay_css:               style