Merge branch 'master' into refactor-related-posts

History.markdown

@@ -1,10 +1,42 @@
 ## HEAD
 ### Major Enhancements
+
 ### Minor Enhancements
+
 ### Bug Fixes
+  * Rename Jekyll::Logger to Jekyll::Stevenson to fix inheritance issue (#1106)
+
 ### Site Enhancements
+  * Add jekyll-contentblocks plugin to docs (#1068)
+  * Make code bits in notes look more natural, more readable (#1089)
+  * Fix logic for `relative_permalinks` instructions on Upgrading page (#1101)
+  * Add docs for post excerpt (#1072)
+  * Add docs for gist tag (#1072)
+
 ### Development Fixes
 
+## 1.0.2 / 2013-05-12
+
+### Major Enhancements
+  * Add `jekyll doctor` command to check site for any known compatibility problems (#1081)
+  * Backwards-compatibilize relative permalinks (#1081)
+
+### Minor Enhancements
+  * Add a `data-lang="<lang>"` attribute to Redcarpet code blocks (#1066)
+  * Deprecate old config `server_port`, match to `port` if `port` isn't set (#1084)
+  * Update pygments.rb version to 0.5.0 (#1061)
+  * Update Kramdown version to 1.0.2 (#1067)
+
+### Bug Fixes
+  * Fix issue when categories are numbers (#1078)
+  * Catching that Redcarpet gem isn't installed (#1059)
+
+### Site Enhancements
+  * Add documentation about `relative_permalinks` (#1081)
+  * Remove pygments-installation instructions, as pygments.rb is bundled with it (#1079)
+  * Move pages to be Pages for realz (#985)
+  * Updated links to Liquid documentation (#1073)
+
 ## 1.0.1 / 2013-05-08
 
 ### Minor Enhancements

bin/jekyll

@@ -86,6 +86,20 @@ command :serve do |c|
 end
 alias_command :server, :serve
 
+command :doctor do |c|
+  c.syntax = 'jekyll doctor'
+  c.description = 'Search site and print specific deprecation warnings'
+
+  c.option '--config CONFIG_FILE[,CONFIG_FILE2,...]', Array, 'Custom configuration file'
+
+  c.action do |args, options|
+    options = normalize_options(options.__hash__)
+    options = Jekyll.configuration(options)
+    Jekyll::Commands::Doctor.process(options)
+  end
+end
+alias_command :hyde, :doctor
+
 command :import do |c|
   c.syntax = 'jekyll import <platform> [options]'
   c.description = 'Import your old blog to Jekyll'

jekyll.gemspec

@@ -4,9 +4,9 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
 
   s.name              = 'jekyll'
-  s.version           = '1.0.1'
+  s.version           = '1.0.2'
   s.license           = 'MIT'
-  s.date              = '2013-05-08'
+  s.date              = '2013-05-12'
   s.rubyforge_project = 'jekyll'
 
   s.summary     = "A simple, blog aware, static site generator."
@@ -27,8 +27,8 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency('classifier', "~> 1.3")
   s.add_runtime_dependency('directory_watcher', "~> 1.4.1")
   s.add_runtime_dependency('maruku', "~> 0.5")
-  s.add_runtime_dependency('kramdown', "~> 0.14")
-  s.add_runtime_dependency('pygments.rb', "~> 0.4.2")
+  s.add_runtime_dependency('kramdown', "~> 1.0.2")
+  s.add_runtime_dependency('pygments.rb', "~> 0.5.0")
   s.add_runtime_dependency('commander', "~> 4.1.3")
   s.add_runtime_dependency('safe_yaml', "~> 0.7.0")
   s.add_runtime_dependency('colorator', "~> 0.1")
@@ -71,6 +71,7 @@ Gem::Specification.new do |s|
     lib/jekyll.rb
     lib/jekyll/command.rb
     lib/jekyll/commands/build.rb
+    lib/jekyll/commands/doctor.rb
     lib/jekyll/commands/new.rb
     lib/jekyll/commands/serve.rb
     lib/jekyll/configuration.rb
@@ -125,34 +126,33 @@ Gem::Specification.new do |s|
     site/_includes/top.html
     site/_layouts/default.html
     site/_layouts/docs.html
-    site/_posts/2012-07-01-configuration.md
-    site/_posts/2012-07-01-contributing.md
-    site/_posts/2012-07-01-deployment-methods.md
-    site/_posts/2012-07-01-extras.md
-    site/_posts/2012-07-01-frontmatter.md
-    site/_posts/2012-07-01-github-pages.md
-    site/_posts/2012-07-01-heroku.md
-    site/_posts/2012-07-01-home.md
-    site/_posts/2012-07-01-installation.md
-    site/_posts/2012-07-01-migrations.md
-    site/_posts/2012-07-01-pages.md
-    site/_posts/2012-07-01-pagination.md
-    site/_posts/2012-07-01-permalinks.md
-    site/_posts/2012-07-01-plugins.md
-    site/_posts/2012-07-01-posts.md
-    site/_posts/2012-07-01-resources.md
-    site/_posts/2012-07-01-sites.md
-    site/_posts/2012-07-01-structure.md
-    site/_posts/2012-07-01-templates.md
-    site/_posts/2012-07-01-troubleshooting.md
-    site/_posts/2012-07-01-upgrading.md
-    site/_posts/2012-07-01-usage.md
-    site/_posts/2012-07-01-variables.md
     site/css/gridism.css
     site/css/normalize.css
     site/css/pygments.css
     site/css/style.css
-    site/docs/index.html
+    site/docs/configuration.md
+    site/docs/contributing.md
+    site/docs/deployment-methods.md
+    site/docs/extras.md
+    site/docs/frontmatter.md
+    site/docs/github-pages.md
+    site/docs/heroku.md
+    site/docs/index.md
+    site/docs/installation.md
+    site/docs/migrations.md
+    site/docs/pages.md
+    site/docs/pagination.md
+    site/docs/permalinks.md
+    site/docs/plugins.md
+    site/docs/posts.md
+    site/docs/resources.md
+    site/docs/sites.md
+    site/docs/structure.md
+    site/docs/templates.md
+    site/docs/troubleshooting.md
+    site/docs/upgrading.md
+    site/docs/usage.md
+    site/docs/variables.md
     site/favicon.png
     site/img/article-footer.png
     site/img/footer-arrow.png
@@ -204,6 +204,7 @@ Gem::Specification.new do |s|
     test/source/_posts/2013-01-12-no-layout.textile
     test/source/_posts/2013-03-19-not-a-post.markdown/.gitkeep
     test/source/_posts/2013-04-11-custom-excerpt.markdown
+    test/source/_posts/2013-05-10-number-category.textile
     test/source/_posts/es/2008-11-21-nested.textile
     test/source/about.html
     test/source/category/_posts/2008-9-23-categories.textile

lib/jekyll.rb

@@ -57,7 +57,7 @@ require_all 'jekyll/tags'
 SafeYAML::OPTIONS[:suppress_warnings] = true
 
 module Jekyll
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 
   # Public: Generate a Jekyll configuration Hash by merging the default
   # options with anything in _config.yml, and adding the given options on top.

lib/jekyll/command.rb

@@ -18,9 +18,9 @@ module Jekyll
       site.process
     rescue Jekyll::FatalException => e
       puts
-      Jekyll::Logger.error "ERROR:", "YOUR SITE COULD NOT BE BUILT:"
-      Jekyll::Logger.error "", "------------------------------------"
-      Jekyll::Logger.error "", e.message
+      Jekyll::Stevenson.error "ERROR:", "YOUR SITE COULD NOT BE BUILT:"
+      Jekyll::Stevenson.error "", "------------------------------------"
+      Jekyll::Stevenson.error "", e.message
       exit(1)
     end
   end

lib/jekyll/commands/build.rb

@@ -17,9 +17,9 @@ module Jekyll
       def self.build(site, options)
         source = options['source']
         destination = options['destination']
-        Jekyll::Logger.info "Source:", source
-        Jekyll::Logger.info "Destination:", destination
-        print Jekyll::Logger.formatted_topic "Generating..."
+        Jekyll::Stevenson.info "Source:", source
+        Jekyll::Stevenson.info "Destination:", destination
+        print Jekyll::Stevenson.formatted_topic "Generating..."
         self.process_site(site)
         puts "done."
       end
@@ -36,14 +36,14 @@ module Jekyll
         source = options['source']
         destination = options['destination']
 
-        Jekyll::Logger.info "Auto-regeneration:", "enabled"
+        Jekyll::Stevenson.info "Auto-regeneration:", "enabled"
 
         dw = DirectoryWatcher.new(source, :glob => self.globs(source, destination), :pre_load => true)
         dw.interval = 1
 
         dw.add_observer do |*args|
           t = Time.now.strftime("%Y-%m-%d %H:%M:%S")
-          print Jekyll::Logger.formatted_topic("Regenerating:") + "#{args.size} files at #{t} "
+          print Jekyll::Stevenson.formatted_topic("Regenerating:") + "#{args.size} files at #{t} "
           self.process_site(site)
           puts  "...done."
         end

lib/jekyll/commands/doctor.rb

@@ -0,0 +1,29 @@
+module Jekyll
+  module Commands
+    class Doctor < Command
+      class << self
+        def process(options)
+          site = Jekyll::Site.new(options)
+          site.read
+
+          unless deprecated_relative_permalinks(site)
+            Jekyll::Stevenson.info "Your test results", "are in. Everything looks fine."
+          end
+        end
+
+        def deprecated_relative_permalinks(site)
+          contains_deprecated_pages = false
+          site.pages.each do |page|
+            if page.uses_relative_permalinks
+              Jekyll::Stevenson.warn "Deprecation:", "'#{page.path}' uses relative" +
+                                  " permalinks which will be deprecated in" +
+                                  " Jekyll v1.1 and beyond."
+              contains_deprecated_pages = true
+            end
+          end
+          contains_deprecated_pages
+        end
+      end
+    end
+  end
+end

lib/jekyll/commands/new.rb

@@ -9,7 +9,7 @@ module Jekyll
         new_blog_path = File.expand_path(args.join(" "), Dir.pwd)
         FileUtils.mkdir_p new_blog_path
         unless Dir["#{new_blog_path}/**/*"].empty?
-          Jekyll::Logger.error "Conflict:", "#{new_blog_path} exists and is not empty."
+          Jekyll::Stevenson.error "Conflict:", "#{new_blog_path} exists and is not empty."
           exit(1)
         end
 

lib/jekyll/configuration.rb

@@ -19,7 +19,10 @@ module Jekyll
       'limit_posts'   => 0,
       'lsi'           => false,
       'future'        => true,           # remove and make true just default
-      'pygments'      => true,           # remove and make true just default
+      'pygments'      => true,
+
+      'relative_permalinks' => true,     # backwards-compatibility with < 1.0
+                                         # will be set to false once 1.1 hits
 
       'markdown'      => 'maruku',
       'permalink'     => 'date',
@@ -112,7 +115,7 @@ module Jekyll
     def read_config_file(file)
       next_config = YAML.safe_load_file(file)
       raise "Configuration file: (INVALID) #{file}".yellow if !next_config.is_a?(Hash)
-      Jekyll::Logger.info "Configuration file:", file
+      Jekyll::Stevenson.info "Configuration file:", file
       next_config
     end
 
@@ -132,9 +135,9 @@ module Jekyll
         end
       rescue SystemCallError
         # Errno:ENOENT = file not found
-        Jekyll::Logger.warn "Configuration file:", "none"
+        Jekyll::Stevenson.warn "Configuration file:", "none"
       rescue => err
-        Jekyll::Logger.warn "WARNING:", "Error reading configuration. " +
+        Jekyll::Stevenson.warn "WARNING:", "Error reading configuration. " +
                      "Using defaults (and options)."
         $stderr.puts "#{err}"
       end
@@ -150,7 +153,7 @@ module Jekyll
       config = clone
       # Provide backwards-compatibility
       if config.has_key?('auto') || config.has_key?('watch')
-        Jekyll::Logger.warn "Deprecation:", "Auto-regeneration can no longer" +
+        Jekyll::Stevenson.warn "Deprecation:", "Auto-regeneration can no longer" +
                             " be set from your configuration file(s). Use the"+
                             " --watch/-w command-line option instead."
         config.delete('auto')
@@ -158,12 +161,21 @@ module Jekyll
       end
 
       if config.has_key? 'server'
-        Jekyll::Logger.warn "Deprecation:", "The 'server' configuration option" +
+        Jekyll::Stevenson.warn "Deprecation:", "The 'server' configuration option" +
                             " is no longer accepted. Use the 'jekyll serve'" +
                             " subcommand to serve your site with WEBrick."
         config.delete('server')
       end
 
+      if config.has_key? 'server_port'
+        Jekyll::Stevenson.warn "Deprecation:", "The 'server_port' configuration option" +
+                            " has been renamed to 'port'. Please update your config" +
+                            " file accordingly."
+        # copy but don't overwrite:
+        config['port'] = config['server_port'] unless config.has_key?('port')
+        config.delete('server_port')
+      end
+
       config
     end
 

lib/jekyll/converters/markdown/redcarpet_parser.rb

@@ -5,7 +5,7 @@ module Jekyll
 
         module CommonMethods
           def add_code_tags(code, lang)
-            code = code.sub(/<pre>/, "<pre><code class=\"#{lang} language-#{lang}\">")
+            code = code.sub(/<pre>/, "<pre><code class=\"#{lang} language-#{lang}\" data-lang=\"#{lang}\">")
             code = code.sub(/<\/pre>/,"</code></pre>")
           end
         end
@@ -52,7 +52,7 @@ module Jekyll
                             include WithoutPygments
                           end
                         end
-        rescue LoadErro
+        rescue LoadError
           STDERR.puts 'You are missing a library required for Markdown. Please run:'
           STDERR.puts '  $ [sudo] gem install redcarpet'
           raise FatalException.new("Missing dependency: redcarpet")

lib/jekyll/convertible.rb

@@ -76,7 +76,7 @@ module Jekyll
     def render_liquid(content, payload, info)
       Liquid::Template.parse(content).render!(payload, info)
     rescue Exception => e
-      Jekyll::Logger.error "Liquid Exception:", "#{e.message} in #{payload[:file]}"
+      Jekyll::Stevenson.error "Liquid Exception:", "#{e.message} in #{payload[:file]}"
       e.backtrace.each do |backtrace|
         puts backtrace
       end

lib/jekyll/deprecator.rb

@@ -18,14 +18,14 @@ module Jekyll
 
     def self.no_subcommand(args)
       if args.size > 0 && args.first =~ /^--/ && !%w[--help --version].include?(args.first)
-        Jekyll::Logger.error "Deprecation:", "Jekyll now uses subcommands instead of just \
+        Jekyll::Stevenson.error "Deprecation:", "Jekyll now uses subcommands instead of just \
                             switches. Run `jekyll help' to find out more."
       end
     end
 
     def self.deprecation_message(args, deprecated_argument, message)
       if args.include?(deprecated_argument)
-        Jekyll::Logger.error "Deprecation:", message
+        Jekyll::Stevenson.error "Deprecation:", message
       end
     end
   end

lib/jekyll/filters.rb

@@ -146,7 +146,7 @@ module Jekyll
       when String
         Time.parse(input)
       else
-        Jekyll::Logger.error "Invalid Date:", "'#{input}' is not a valid datetime."
+        Jekyll::Stevenson.error "Invalid Date:", "'#{input}' is not a valid datetime."
         exit(1)
       end
     end

lib/jekyll/logger.rb

@@ -1,7 +1,7 @@
 require 'logger'
 
 module Jekyll
-  class Logger < Logger
+  class Stevenson < Logger
     # Public: Print a jekyll message to stdout
     #
     # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.

lib/jekyll/page.rb

@@ -64,7 +64,11 @@ module Jekyll
       return @url if @url
 
       url = if permalink
-        permalink
+        if site.config['relative_permalinks']
+          File.join(@dir, permalink)
+        else
+          permalink
+        end
       else
         {
           "path"       => @dir,
@@ -114,7 +118,14 @@ module Jekyll
       self.data.deep_merge({
         "url"        => self.url,
         "content"    => self.content,
-        "path"       => self.data['path'] || File.join(@dir, @name).sub(/\A\//, '') })
+        "path"       => self.data['path'] || path })
+    end
+
+    # The path to the source file
+    #
+    # Returns the path to the source file
+    def path
+      File.join(@dir, @name).sub(/\A\//, '')
     end
 
     # Obtain destination path.
@@ -144,5 +155,9 @@ module Jekyll
     def index?
       basename == 'index'
     end
+
+    def uses_relative_permalinks
+      permalink && @dir != "" && site.config['relative_permalinks']
+    end
   end
 end

lib/jekyll/post.rb

@@ -76,7 +76,7 @@ module Jekyll
 
     def populate_categories
       if self.categories.empty?
-        self.categories = self.data.pluralized_array('category', 'categories').map {|c| c.downcase}
+        self.categories = self.data.pluralized_array('category', 'categories').map {|c| c.to_s.downcase}
       end
       self.categories.flatten!
     end

lib/jekyll/site.rb

@@ -229,6 +229,7 @@ module Jekyll
       end
 
       self.pages.each do |page|
+        relative_permalinks_deprecation_method if page.uses_relative_permalinks
         page.render(self.layouts, payload)
       end
 
@@ -416,5 +417,18 @@ module Jekyll
       post.categories.each { |c| self.categories[c] << post }
       post.tags.each { |c| self.tags[c] << post }
     end
+
+    def relative_permalinks_deprecation_method
+      if config['relative_permalinks'] && !@deprecated_relative_permalinks
+        $stderr.puts # Places newline after "Generating..."
+        Jekyll::Stevenson.warn "Deprecation:", "Starting in 1.1, permalinks for pages" +
+                                            " in subfolders must be relative to the" +
+                                            " site source directory, not the parent" +
+                                            " directory. Check http://jekyllrb.com/docs/upgrading/"+
+                                            " for more info."
+        $stderr.print Jekyll::Stevenson.formatted_topic("") + "..." # for "done."
+        @deprecated_relative_permalinks = true
+      end
+    end
   end
 end

site/_config.yml

@@ -1,3 +1,3 @@
-permalink: /docs/:categories/:title
 pygments: true
+relative_permalinks: false
 gauges_id: 503c5af6613f5d0f19000027

site/_includes/primary-nav-items.html

@@ -3,7 +3,7 @@
     <a href="{{ site.url }}/">Overview</a>
   </li>
   <li class="{% unless page.overview %}current{% endunless %}">
-    <a href="{{ site.url }}/docs">Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">umentation</span></a>
+    <a href="{{ site.url }}/docs/home">Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">umentation</span></a>
   </li>
   <li class="">
     <a href="https://github.com/mojombo/jekyll"><span class="hide-on-mobiles">View on </span>GitHub</a>

site/_posts/2012-07-01-extras.md

@@ -1,114 +0,0 @@
----
-layout: docs
-title: Extras
-prev_section: plugins
-next_section: github-pages
----
-
-There are a number of (optional) extra features that Jekyll supports that you
-may want to install, depending on how you plan to use Jekyll.
-
-## Pygments
-
-If you want syntax highlighting via the `{% raw %}{% highlight %}{% endraw %}`
-tag in your posts, you’ll need to install [Pygments](http://pygments.org/).
-
-### Installing Pygments on OSX
-
-Mac OS X (Leopard onwards) comes preinstalled with Python, so on just about any
-OS X machine you can install Pygments simply by running:
-
-{% highlight bash %}
-$ sudo easy_install Pygments
-{% endhighlight %}
-
-#### Installing Pygments using Homebrew
-
-Alternatively, you can install Pygments with
-[Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for
-OS X:
-
-{% highlight bash %}
-$ brew install python
-# export PATH="/usr/local/share/python:${PATH}"
-$ pip install pygments
-{% endhighlight %}
-
-<div class="note">
-  <h5>Homebrew's executable paths</h5>
-  <p>
-    Homebrew doesn’t symlink the executables for you. For the Homebrew default
-    Cellar location and Python 2.7, be sure to add `/usr/local/share/python` to
-    your `PATH`. For more information, check out
-    <a href="https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python">the
-    Homebrew wiki</a>.
-  </p>
-</div>
-
-#### Installing Pygments using MacPorts
-
-If you use MacPorts, you can install Pygments by running:
-
-{% highlight bash %}
-$ sudo port install python25 py25-pygments
-{% endhighlight %}
-
-Seriously though, you should check out
-[Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
-
-### Installing Pygments on Arch Linux
-
-You can install Pygments using the pacman package manager as follows:
-
-{% highlight bash %}
-$ sudo pacman -S python-pygments
-{% endhighlight %}
-
-Or to use python2 for Pygments:
-
-{% highlight bash %}
-$ sudo pacman -S python2-pygments
-{% endhighlight %}
-
-### Installing Pygments on Ubuntu and Debian
-
-{% highlight bash %}
-$ sudo apt-get install python-pygments
-{% endhighlight %}
-
-### Installing Pygments on RedHat, Fedora, and CentOS
-
-{% highlight bash %}
-$ sudo yum install python-pygments
-{% endhighlight %}
-
-### Installing Pygments on Gentoo
-
-{% highlight bash %}
-$ sudo emerge -av dev-python/pygments
-{% endhighlight %}
-
-## LaTeX Support
-
-Maruku comes with optional support for LaTeX to PNG rendering via blahtex
-(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
-Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
-fork](http://github.com/remi/maruku).
-
-## RDiscount
-
-If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
-of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have
-it installed:
-
-{% highlight bash %}
-$ sudo gem install rdiscount
-{% endhighlight %}
-
-And then specify RDiscount as the Markdown engine in your `_config.yml` file to
-have Jekyll run with that option.
-
-{% highlight bash %}
-# In _config.yml
-markdown: rdiscount
-{% endhighlight %}

site/css/style.css

@@ -519,7 +519,7 @@ pre, code {
   }
 }
 
-.highlight, p > pre, p > code, p > nobr > code, li > code {
+.highlight, p > pre, p > code, p > nobr > code, li > code, h5 > code, .note > code {
   background: #333;
   color: #fff;
   border-radius: 5px;
@@ -528,6 +528,13 @@ pre, code {
     0 -1px 0 rgba(0,0,0,.5);
 }
 
+.note code {
+  background-color: rgba(0,0,0,0.2);
+  margin-left: 2.5px;
+  margin-right: 2.5px;
+  font-size: 0.8em;
+}
+
 .highlight {
   padding: 10px 0;
   width: 100%;

site/docs/configuration.md

@@ -3,6 +3,7 @@ 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
@@ -252,6 +253,8 @@ show_drafts: nil
 limit_posts: 0
 pygments:    true
 
+relative_permalinks: true
+
 permalink:     date
 paginate_path: 'page:num'
 

site/docs/contributing.md

@@ -3,6 +3,7 @@ layout: docs
 title: Contributing
 prev_section: deployment-methods
 next_section: troubleshooting
+permalink: /docs/contributing/
 ---
 
 So you've got an awesome idea to throw into Jekyll. Great! Please keep the

site/docs/deployment-methods.md

@@ -3,6 +3,7 @@ layout: docs
 title: Deployment methods
 prev_section: github-pages
 next_section: contributing
+permalink: /docs/deployment-methods/
 ---
 
 Sites built using Jekyll can be deployed in a large number of ways due to the static nature of the generated output. A few of the most common deployment techniques are described below.

site/docs/extras.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+title: Extras
+prev_section: plugins
+next_section: github-pages
+permalink: /docs/extras/
+---
+
+There are a number of (optional) extra features that Jekyll supports that you
+may want to install, depending on how you plan to use Jekyll.
+
+## LaTeX Support
+
+Maruku comes with optional support for LaTeX to PNG rendering via blahtex
+(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
+Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
+fork](http://github.com/remi/maruku).
+
+## RDiscount
+
+If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
+of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have
+it installed:
+
+{% highlight bash %}
+$ sudo gem install rdiscount
+{% endhighlight %}
+
+And then specify RDiscount as the Markdown engine in your `_config.yml` file to
+have Jekyll run with that option.
+
+{% highlight bash %}
+# In _config.yml
+markdown: rdiscount
+{% endhighlight %}

site/docs/frontmatter.md

@@ -3,6 +3,7 @@ layout: docs
 title: Front-matter
 prev_section: configuration
 next_section: posts
+permalink: /docs/frontmatter/
 ---
 
 The front-matter is where Jekyll starts to get really cool. Any file that

site/docs/github-pages.md

@@ -3,6 +3,7 @@ layout: docs
 title: GitHub Pages
 prev_section: extras
 next_section: deployment-methods
+permalink: /docs/github-pages/
 ---
 
 [GitHub Pages](http://pages.github.com) are public web pages for users,

site/docs/heroku.md

@@ -3,6 +3,7 @@ layout: docs
 title: Heroku
 prev_section: github-pages
 next_section: manual-deployment
+permalink: /docs/heroku/
 ---
 
 Move along, people. Nothing to see here.

site/docs/index.html

@@ -1,11 +0,0 @@
-<!DOCTYPE HTML>
-<html lang="en-US">
-<head>
-  <meta charset="UTF-8">
-  <meta http-equiv="refresh" content="0;url=home">
-  <title>Jekyll</title>
-</head>
-<body style="background: #333;">
-
-</body>
-</html>

site/docs/index.md

@@ -2,6 +2,7 @@
 layout: docs
 title: Welcome
 next_section: installation
+permalink: /docs/home/
 ---
 
 This site aims to be a comprehensive guide to Jekyll. We’ll cover topics such
@@ -15,7 +16,8 @@ development of Jekyll itself.
 Jekyll is a simple, blog-aware, static site generator. It takes a template
 directory containing raw text files in various formats, runs it through
 [Markdown](http://daringfireball.net/projects/markdown/) (or
-[Textile](http://textile.sitemonks.com/)) and [Liquid](http://liquidmarkup.org/)
+[Textile](http://textile.sitemonks.com/)) and
+[Liquid](http://wiki.shopify.com/Liquid)
 converters, and spits out a complete, ready-to-publish static website suitable
 for serving with your favorite web server. Jekyll also happens to be the engine
 behind [GitHub Pages](http://pages.github.com), which means you can use Jekyll

site/docs/installation.md

@@ -3,6 +3,7 @@ layout: docs
 title: Installation
 prev_section: home
 next_section: usage
+permalink: /docs/installation/
 ---
 
 Getting Jekyll installed and ready-to-go should only take a few minutes. If it

site/docs/migrations.md

@@ -3,6 +3,7 @@ layout: docs
 title: Blog migrations
 prev_section: variables
 next_section: templates
+permalink: /docs/migrations/
 ---
 
 If you’re switching to Jekyll from another blogging system, Jekyll’s importers

site/docs/pages.md

@@ -3,6 +3,7 @@ layout: docs
 title: Creating pages
 prev_section: posts
 next_section: variables
+permalink: /docs/pages/
 ---
 
 In addition to [writing posts](../posts), another thing you may want to do with

site/docs/pagination.md

@@ -3,6 +3,7 @@ layout: docs
 title: Pagination
 prev_section: permalinks
 next_section: plugins
+permalink: /docs/pagination/
 ---
 
 With many websites—especially blogs—it’s very common to break the main listing

site/docs/permalinks.md

@@ -3,6 +3,7 @@ layout: docs
 title: Permalinks
 prev_section: templates
 next_section: pagination
+permalink: /docs/permalinks/
 ---
 
 Jekyll supports a flexible way to build your site’s URLs. You can specify the

site/docs/plugins.md

@@ -3,6 +3,7 @@ layout: docs
 title: Plugins
 prev_section: assets
 next_section: extras
+permalink: /docs/plugins/
 ---
 
 Jekyll has a plugin system with hooks that allow you to create custom generated
@@ -403,6 +404,7 @@ There are a few useful, prebuilt plugins at the following locations:
 - [jekyll-rendering](https://github.com/blackwinter/jekyll-rendering): Jekyll plugin to provide alternative rendering engines.
 - [jekyll-pagination](https://github.com/blackwinter/jekyll-pagination): Jekyll plugin to extend the pagination generator.
 - [jekyll-tagging](https://github.com/pattex/jekyll-tagging): Jekyll plugin to automatically generate a tag cloud and tag pages.
+- [jekyll-contentblocks](https://github.com/rustygeldmacher/jekyll-contentblocks): Lets you use Rails-like content_for tags in your templates, for passing content from your posts up to your layouts.
 - [Generate YouTube Embed (tag)](https://gist.github.com/1805814) by [joelverhagen](https://github.com/joelverhagen): Jekyll plugin which allows you to embed a YouTube video in your page with the YouTube ID. Optionally specify width and height dimensions. Like “oEmbed Tag” but just for YouTube.
 - [JSON Filter](https://gist.github.com/1850654) by [joelverhagen](https://github.com/joelverhagen): filter that takes input text and outputs it as JSON. Great for rendering JavaScript.
 - [jekyll-beastiepress](https://github.com/okeeblow/jekyll-beastiepress): FreeBSD utility tags for Jekyll sites.

site/docs/posts.md

@@ -3,6 +3,7 @@ layout: docs
 title: Writing posts
 prev_section: frontmatter
 next_section: pages
+permalink: /docs/posts/
 ---
 
 One of Jekyll’s best aspects is that it is “blog aware”. What does this mean,
@@ -95,7 +96,7 @@ Linking to a PDF for readers to download:
 It’s all well and good to have posts in a folder, but a blog is no use unless
 you have a list of posts somewhere. Creating an index of posts on another page
 (or in a [template](../templates)) is easy, thanks to the [Liquid template
-language](http://liquidmarkup.org/) and its tags. Here’s a basic example of how
+language](http://wiki.shopify.com/Liquid) and its tags. Here’s a basic example of how
 to create a list of links to your blog posts:
 
 {% highlight html %}
@@ -112,6 +113,28 @@ Of course, you have full control over how (and where) you display your posts,
 and how you structure your site. You should read more about [how templates
 work](../templates) with Jekyll if you want to know more.
 
+## Post excerpts
+
+Each post automatically takes the first block of text, from the beginning of the content
+to the first occurrence of `excerpt_separator`, and sets it as the `post.excerpt`.
+Take the above example of an index of posts. Perhaps you want to include
+a little hint about the post's content by adding the first paragraph of each of your
+posts:
+
+{% highlight html %}
+<ul>
+  {% raw %}{% for post in site.posts %}{% endraw %}
+    <li>
+      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+      <p>{% raw %}{{ post.excerpt }}{% endraw %}</p>
+    </li>
+  {% raw %}{% endfor %}{% endraw %}
+</ul>
+{% endhighlight %}
+
+If you don't like the automatically-generated post excerpt, it can be overridden by adding
+`excerpt` to your post's YAML front-matter.
+
 ## Highlighting code snippets
 
 Jekyll also has built-in support for syntax highlighting of code snippets using

site/docs/resources.md

@@ -3,6 +3,7 @@ layout: docs
 title: Resources
 prev_section: sites
 next_section: upgrading
+permalink: /docs/resources/
 ---
 
 Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.

site/docs/sites.md

@@ -3,6 +3,7 @@ layout: docs
 title: Sites using Jekyll
 prev_section: troubleshooting
 next_section: resources
+permalink: /docs/sites/
 ---
 
 It’s interesting to see what designs and features others have come up

site/docs/structure.md

@@ -3,6 +3,7 @@ layout: docs
 title: Directory structure
 prev_section: usage
 next_section: configuration
+permalink: /docs/structure/
 ---
 
 Jekyll is, at its core, a text transformation engine. The concept behind the

site/docs/templates.md

@@ -3,9 +3,10 @@ layout: docs
 title: Templates
 prev_section: migrations
 next_section: permalinks
+permalink: /docs/templates/
 ---
 
-Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to
+Jekyll uses the [Liquid](http://wiki.shopify.com/Liquid) templating language to
 process templates. All of the [standard Liquid tags and
 filters](http://wiki.github.com/shopify/liquid/liquid-for-designers) are
 supported, Jekyll even adds a few handy filters and tags of its own to make
@@ -233,3 +234,21 @@ You can also use this tag to create a link to a post in Markdown as follows:
 [Name of Link]({% post_url 2010-07-21-name-of-post %})
 {% endraw %}
 {% endhighlight %}
+
+### Gist
+
+Use the `gist` tag to easily embed a GitHub Gist onto your site:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 %}
+{% endraw %}
+{% endhighlight %}
+
+You may also optionally specify the filename in the gist to display:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 result.md %}
+{% endraw %}
+{% endhighlight %}

site/docs/troubleshooting.md

@@ -3,6 +3,7 @@ layout: docs
 title: Troubleshooting
 prev_section: contributing
 next_section: sites
+permalink: /docs/troubleshooting/
 ---
 
 If you ever run into problems installing or using Jekyll, here’s a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please [report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll community can make everyone’s experience better.

site/docs/upgrading.md

@@ -2,9 +2,10 @@
 layout: docs
 title: Upgrading
 prev_section: resources
+permalink: /docs/upgrading/
 ---
 
-Upgrading from an older version of Jekyll? A few things have changed in 1.0.0
+Upgrading from an older version of Jekyll? A few things have changed in 1.0
 that you'll want to know about.
 
 
@@ -24,14 +25,33 @@ and `jekyll serve` to do the same. And if you want Jekyll to automatically
 rebuild each time a file changes, just add the `--watch` flag at the end.
 
 <div class="note info">
-  <h5 markdown="1">Watching and Serving</h5>
+  <h5>Watching and Serving</h5>
   <p markdown="1">With the new subcommands, the way sites are previewed locally
    changed a bit. Instead of specifying `server: true` in the site's
    configuration file, use `jekyll serve`. The same hold's true for
-   `watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
+   `watch: true`. Instead, use the `&#45;&#45;watch` flag with either `jekyll serve`
     or `jekyll build`.</p>
 </div>
 
+### Absolute Permalinks
+
+In Jekyll v1.0, we introduced absolute permalinks for pages in subdirectories.
+Until v1.1, it is **opt-in**. Starting with v1.1, however, absolute permalinks
+will become **opt-out**, meaning Jekyll will default to using absolute permalinks
+instead of relative permalinks.
+
+* To use absolute permalinks, set `relative_permalinks: false` in your configuration file.
+* To continue using relative permalinks, set `relative_permalinks: true` in your configuration file.
+
+<div class="note warning" id="absolute-permalinks-warning">
+  <h5 markdown="1">Absolute permalinks will be default in v1.1 and on</h5>
+  <p markdown="1">
+    Starting with Jekyll v1.1.0, `relative_permalinks` will default to `false`,
+    meaning all pages will be built using the absolute permalink behaviour.
+    The switch will still exist until v2.0.
+  </p>
+</div>
+
 ### Custom Config File
 
 Rather than passing individual flags via the command line, you can now pass an
@@ -53,14 +73,14 @@ to one or more config files (comma-delimited, no spaces).
 * `--paginate`
 
 <div class="note info">
-  <h5 markdown="1">The `--config` explicitly specifies your configuration file(s)</h5>
-  <p markdown="1">If you use the `--config` flag, Jekyll will ignore your
-    `config.yml` file. Want to merge a custom configuration with the normal
+  <h5>The config flag explicitly specifies your configuration file(s)</h5>
+  <p markdown="1">If you use the `&#45;&#45;config` flag, Jekyll will ignore your
+    `&#95;config.yml` file. Want to merge a custom configuration with the normal
     configuration? No problem. Jekyll will accept more than one custom config
     file via the command line. Config files cascade from right to left, such
-    that if I run `jekyll serve --config config.yml,config-dev.yml`,
-    the values in the config files on the right (`config-dev.yml`) overwrite
-    those on the left (`config.yml`) when both contain the same key.</p>
+    that if I run `jekyll serve &#45;&#45;config &#95;config.yml,&#95;config-dev.yml`,
+    the values in the config files on the right (`&#95;config-dev.yml`) overwrite
+    those on the left (`&#95;config.yml`) when both contain the same key.</p>
 </div>
 
 ### Draft posts
@@ -69,14 +89,15 @@ Jekyll now lets you write draft posts, and allows you to easily preview how
 they will look prior to publishing. To start a draft, simply create a folder
 called `_drafts` in your site's source directory (e.g., alongside `_posts`),
 and add a new markdown file to it. To preview your new post, simply run the
-`Jekyll serve` command with the `--drafts` flag.
+`jekyll serve` command with the `--drafts` flag.
 
 <div class="note info">
   <h5 markdown="1">Drafts don't have dates</h5>
-  <p markdown="1">Unlike posts, drafts don't have a date, since they haven't
-  been published yet. Rather than naming your draft something like
-  `2013-07-01-my-draft-post.md`, simply name the file what you'd like your
-  post to eventually be titled, here `my-draft-post.md`.</p>
+  <p markdown="1">
+    Unlike posts, drafts don't have a date, since they haven't
+    been published yet. Rather than naming your draft something like
+    `2013-07-01-my-draft-post.md`, simply name the file what you'd like your
+    post to eventually be titled, here `my-draft-post.md`.</p>
 </div>
 
 ### Baseurl

site/docs/usage.md

@@ -3,6 +3,7 @@ layout: docs
 title: Basic Usage
 prev_section: installation
 next_section: structure
+permalink: /docs/usage/
 ---
 
 The Jekyll gem makes a `jekyll` executable available to you in your Terminal

site/docs/variables.md

@@ -3,6 +3,7 @@ layout: docs
 title: Variables
 prev_section: pages
 next_section: migrations
+permalink: /docs/variables/
 ---
 
 Jekyll traverses your site looking for files to process. Any files with [YAML

site/index.html

@@ -18,19 +18,19 @@ overview: true
       <p>
         No more databases, comment moderation, or pesky updates to install—just <em>your content</em>.
       </p>
-      <a href="{% post_url 2012-07-01-usage %}" class="">How Jekyll works &rarr;</a>
+      <a href="/docs/usage" class="">How Jekyll works &rarr;</a>
     </div>
     <div class="unit one-third">
       <h2>Static</h2>
-      <p><a href="http://daringfireball.net/projects/markdown/">Markdown</a> (or <a href="http://textile.sitemonks.com/">Textile</a>), <a href="http://liquidmarkup.org/">Liquid</a>, HTML <span class="amp">&amp;</span> CSS go in. Static sites come out ready for deployment.</p>
-      <a href="{% post_url 2012-07-01-templates %}" class="">Jekyll template guide &rarr;</a>
+      <p><a href="http://daringfireball.net/projects/markdown/">Markdown</a> (or <a href="http://textile.sitemonks.com/">Textile</a>), <a href="http://wiki.shopify.com/Liquid">Liquid</a>, HTML <span class="amp">&amp;</span> CSS go in. Static sites come out ready for deployment.</p>
+      <a href="/docs/templates" class="">Jekyll template guide &rarr;</a>
     </div>
     <div class="unit one-third">
       <h2>Blog-aware</h2>
       <p>
         Permalinks, categories, pages, posts, and custom layouts are all first-class citizens here.
       </p>
-      <a href="{% post_url 2012-07-01-migrations %}" class="">Migrate your blog &rarr;</a>
+      <a href="/docs/migrations" class="">Migrate your blog &rarr;</a>
     </div>
     <div class="clear"></div>
   </div>

test/source/_posts/2013-05-10-number-category.textile

@@ -0,0 +1,7 @@
+---
+layout: default
+title: Number Category in YAML
+category: 2013
+---
+
+Please make me pass

test/test_generated_site.rb

@@ -14,7 +14,7 @@ class TestGeneratedSite < Test::Unit::TestCase
     end
 
     should "ensure post count is as expected" do
-      assert_equal 33, @site.posts.size
+      assert_equal 34, @site.posts.size
     end
 
     should "insert site.posts into the index" do

test/test_post.rb

@@ -423,6 +423,12 @@ class TestPost < Test::Unit::TestCase
         assert_equal [], post.categories
       end
       
+      should "recognize number category in yaml" do
+        post = setup_post("2013-05-10-number-category.textile")
+        assert post.categories.include?('2013')
+        assert !post.categories.include?(2013)
+      end
+
       should "recognize tag in yaml" do
         post = setup_post("2009-05-18-tag.textile")
         assert post.tags.include?('code')

test/test_redcarpet.rb

@@ -32,7 +32,7 @@ class TestRedcarpet < Test::Unit::TestCase
       end
 
       should "render fenced code blocks with syntax highlighting" do
-        assert_equal "<div class=\"highlight\"><pre><code class=\"ruby language-ruby\"><span class=\"nb\">puts</span> <span class=\"s2\">&quot;Hello world&quot;</span>\n</code></pre></div>", @markdown.convert(
+        assert_equal "<div class=\"highlight\"><pre><code class=\"ruby language-ruby\" data-lang=\"ruby\"><span class=\"nb\">puts</span> <span class=\"s2\">&quot;Hello world&quot;</span>\n</code></pre></div>", @markdown.convert(
           <<-EOS
 ```ruby
 puts "Hello world"
@@ -48,7 +48,7 @@ puts "Hello world"
       end
 
       should "render fenced code blocks without syntax highlighting" do
-        assert_equal "<div class=\"highlight\"><pre><code class=\"ruby language-ruby\">puts &quot;Hello world&quot;\n</code></pre></div>", @markdown.convert(
+        assert_equal "<div class=\"highlight\"><pre><code class=\"ruby language-ruby\" data-lang=\"ruby\">puts &quot;Hello world&quot;\n</code></pre></div>", @markdown.convert(
           <<-EOS
 ```ruby
 puts "Hello world"

test/test_site.rb

@@ -172,7 +172,7 @@ class TestSite < Test::Unit::TestCase
 
       posts = Dir[source_dir("**", "_posts", "**", "*")]
       posts.delete_if { |post| File.directory?(post) && !Post.valid?(post) }
-      categories = %w(bar baz category foo z_category publish_test win).sort
+      categories = %w(2013 bar baz category foo z_category publish_test win).sort
 
       assert_equal posts.size - @num_invalid_posts, @site.posts.size
       assert_equal categories, @site.categories.keys.sort