diff --git a/.gitignore b/.gitignore index ab54fd1b44e..9c7a17eba10 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,5 @@ _site/ .bundle/ .DS_Store bbin/ +gh-pages/ +site/_site/ diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 00000000000..74f5f164b7f --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +1.9.3-p362 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..fa6fb8075f0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +Contribute +========== + +So you've got an awesome idea to throw into Jekyll. Great! Please keep the following in mind: + +* **Contributions will not be accepted without tests.** +* If you're creating a small fix or patch to an existing feature, just a simple test will do. Please stay in the confines of the current test suite and use [Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and [RR](http://github.com/btakita/rr/tree/master). +* If it's a brand new feature, make sure to create a new [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps where appropriate. Also, whipping up some documentation in your fork's wiki would be appreciated, and once merged it will be transferred over to the main wiki. + +Test Dependencies +----------------- + +To run the test suite and build the gem you'll need to install Jekyll's dependencies. Jekyll uses Bundler, so a quick run of the bundle command and you're all set! + + $ bundle + +Before you start, run the tests and make sure that they pass (to confirm your environment is configured properly): + + $ rake test + $ rake features + +Workflow +-------- + +Here's the most direct way to get your work merged into the project: +* Fork the project +* Clone down your fork ( `git clone git://github.com//jekyll.git` ) +* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ) +* Hack away, add tests. Not necessarily in that order. +* Make sure everything still passes by running `rake` +* If necessary, rebase your commits into logical chunks, without errors +* Push the branch up ( `git push origin my_awesome_feature` ) +* Create an issue with a description and link to your branch + +Gotchas +------- + +* If you want to bump the gem version, please put that in a separate commit. This way, the maintainers can control when the gem gets released. +* Try to keep your patch(es) based from the latest commit on mojombo/jekyll. The easier it is to apply your work, the less work the maintainers have to do, which is always a good thing. +* Please don't tag your GitHub issue with [fix], [feature], etc. The maintainers actively read the issues and will label it once they come across it. + +Finally... +---------- + +Thanks! Hacking on Jekyll should be fun, and if for some reason it's a pain to do let us know so we can fix it. diff --git a/History.txt b/History.txt index e7e832b15e6..d65aad875fb 100644 --- a/History.txt +++ b/History.txt @@ -1,4 +1,14 @@ == HEAD + * Minor Enhancements + * Add source and destination directory protection (#535) + * Better YAML error message (#718) + * Bug Fixes + * Prevent custom destination from causing continuous regen (#528) + * Site Enhancements + * Bring site into master branch with better preview/deploy (#709) + * Redesigned site (#583) + +== 0.12.0 / 2012-12-22 * Minor Enhancements * Add ability to explicitly specify included files (#261) * Add --default-mimetype option (#279) @@ -7,12 +17,16 @@ * Allow multiple plugin dirs to be specified (#438) * Inline TOC token support for RDiscount (#333) * Add the option to specify the paginated url format (#342) + * Swap out albino for pygments.rb (#569) + * Support Redcarpet 2 and fenced code blocks (#619) + * Better reporting of Liquid errors (#624) * Bug Fixes * Allow some special characters in highlight names * URL escape category names in URL generation (#360) * Fix error with limit_posts (#442) * Properly select dotfile during directory scan (#363, #431, #377) * Allow setting of Kramdown smart_quotes (#482) + * Ensure front-matter is at start of file (#562) == 0.11.2 / 2011-12-27 * Bug Fixes diff --git a/README.textile b/README.textile index 4cefb9ffa97..529e1e7dcfb 100644 --- a/README.textile +++ b/README.textile @@ -22,19 +22,20 @@ h2. Diving In h2. Runtime Dependencies -* RedCloth: Textile support (Ruby) -* Liquid: Templating system (Ruby) * Classifier: Generating related posts (Ruby) -* Maruku: Default markdown engine (Ruby) * Directory Watcher: Auto-regeneration of sites (Ruby) +* Kramdown: Markdown-superset converter (Ruby) +* Liquid: Templating system (Ruby) +* Maruku: Default markdown engine (Ruby) * Pygments: Syntax highlighting (Python) h2. Developer Dependencies -* Shoulda: Test framework (Ruby) -* RR: Mocking (Ruby) -* RedGreen: Nicer test output (Ruby) * RDiscount: Discount Markdown Processor (Ruby) +* RedCloth: Textile support (Ruby) +* RedGreen: Nicer test output (Ruby) +* RR: Mocking (Ruby) +* Shoulda: Test framework (Ruby) h2. License diff --git a/Rakefile b/Rakefile index 8eb1360d6fa..ff52d6772aa 100644 --- a/Rakefile +++ b/Rakefile @@ -109,6 +109,72 @@ rescue LoadError end end +############################################################################# +# +# Site tasks - http://jekyllrb.com +# +############################################################################# + +namespace :site do + desc "Generate and view the site locally" + task :preview do + require "launchy" + + # Yep, it's a hack! Wait a few seconds for the Jekyll site to generate and + # then open it in a browser. Someday we can do better than this, I hope. + Thread.new do + sleep 4 + puts "Opening in browser..." + Launchy.open("http://localhost:4000") + end + + # Generate the site in server mode. + puts "Running Jekyll..." + Dir.chdir("site") do + sh "#{File.expand_path('bin/jekyll', File.dirname(__FILE__))} --server" + end + end + + desc "Commit the local site to the gh-pages branch and publish to GitHub Pages" + task :publish do + # Failsafe. Remove this once it has been done. + puts "Make sure to merge #583 into gh-pages before deploying." + exit(1) + + # Ensure the gh-pages dir exists so we can generate into it. + puts "Checking for gh-pages dir..." + unless File.exist?("./gh-pages") + puts "No gh-pages directory found. Run the following commands first:" + puts " `git clone git@github.com:mojombo/jekyll gh-pages" + puts " `cd gh-pages" + puts " `git checkout gh-pages`" + exit(1) + end + + # Ensure gh-pages branch is up to date. + Dir.chdir('gh-pages') do + sh "git pull origin gh-pages" + end + + # Copy to gh-pages dir. + puts "Copying site to gh-pages branch..." + Dir.glob("site/*") do |path| + next if path == "_site" + sh "cp -R #{path} gh-pages/" + end + + # Commit and push. + puts "Committing and pushing to GitHub Pages..." + sha = `git log`.match(/[a-z0-9]{40}/)[0] + Dir.chdir('gh-pages') do + sh "git add ." + sh "git commit -m 'Updating to #{sha}.'" + sh "git push origin gh-pages" + end + puts 'Done.' + end +end + ############################################################################# # # Packaging tasks diff --git a/bin/jekyll b/bin/jekyll index 03c26c22e8a..b8467fb112d 100755 --- a/bin/jekyll +++ b/bin/jekyll @@ -229,10 +229,10 @@ source = options['source'] destination = options['destination'] # Files to watch -def globs(source) +def globs(source, destination) Dir.chdir(source) do dirs = Dir['*'].select { |x| File.directory?(x) } - dirs -= ['_site'] + dirs -= [destination] dirs = dirs.map { |x| "#{x}/**/*" } dirs += ['*'] end @@ -249,7 +249,7 @@ if options['auto'] dw = DirectoryWatcher.new(source) dw.interval = 1 - dw.glob = globs(source) + dw.glob = globs(source, destination) dw.add_observer do |*args| t = Time.now.strftime("%Y-%m-%d %H:%M:%S") diff --git a/jekyll.gemspec b/jekyll.gemspec index 55201ae8146..dbbe43867d4 100644 --- a/jekyll.gemspec +++ b/jekyll.gemspec @@ -4,8 +4,9 @@ Gem::Specification.new do |s| s.rubygems_version = '1.3.5' s.name = 'jekyll' - s.version = '0.11.2' - s.date = '2011-12-27' + s.version = '0.12.0' + s.license = 'MIT' + s.date = '2012-12-22' s.rubyforge_project = 'jekyll' s.summary = "A simple, blog aware, static site generator." @@ -27,7 +28,7 @@ Gem::Specification.new do |s| s.add_runtime_dependency('directory_watcher', "~> 1.1") s.add_runtime_dependency('maruku', "~> 0.5") s.add_runtime_dependency('kramdown', "~> 0.13.4") - s.add_runtime_dependency('pygments.rb', "~> 0.2.12") + s.add_runtime_dependency('pygments.rb', "~> 0.3.2") s.add_development_dependency('rake', "~> 0.9") s.add_development_dependency('rdoc', "~> 3.11") @@ -37,7 +38,8 @@ Gem::Specification.new do |s| s.add_development_dependency('cucumber', "1.1") s.add_development_dependency('RedCloth', "~> 4.2") s.add_development_dependency('rdiscount', "~> 1.6") - s.add_development_dependency('redcarpet', "~> 1.9") + s.add_development_dependency('redcarpet', "~> 2.1.1") + s.add_development_dependency('launchy', "~> 2.1.2") # = MANIFEST = s.files = %w[ @@ -74,10 +76,12 @@ Gem::Specification.new do |s| lib/jekyll/migrators/csv.rb lib/jekyll/migrators/drupal.rb lib/jekyll/migrators/enki.rb + lib/jekyll/migrators/joomla.rb lib/jekyll/migrators/marley.rb lib/jekyll/migrators/mephisto.rb lib/jekyll/migrators/mt.rb lib/jekyll/migrators/posterous.rb + lib/jekyll/migrators/rss.rb lib/jekyll/migrators/textpattern.rb lib/jekyll/migrators/tumblr.rb lib/jekyll/migrators/typo.rb @@ -90,6 +94,9 @@ Gem::Specification.new do |s| lib/jekyll/static_file.rb lib/jekyll/tags/highlight.rb lib/jekyll/tags/include.rb + lib/jekyll/tags/post_url.rb + test/fixtures/broken_front_matter1.erb + test/fixtures/front_matter.erb test/helper.rb test/source/.htaccess test/source/_includes/sig.markdown @@ -132,6 +139,7 @@ Gem::Specification.new do |s| test/source/z_category/_posts/2008-9-23-categories.textile test/suite.rb test/test_configuration.rb + test/test_convertible.rb test/test_core_ext.rb test/test_filters.rb test/test_generated_site.rb @@ -141,9 +149,9 @@ Gem::Specification.new do |s| test/test_post.rb test/test_rdiscount.rb test/test_redcarpet.rb + test/test_redcloth.rb test/test_site.rb test/test_tags.rb - test/test_redcloth.rb ] # = MANIFEST = diff --git a/lib/jekyll.rb b/lib/jekyll.rb index f74e428b488..2e5a681e733 100644 --- a/lib/jekyll.rb +++ b/lib/jekyll.rb @@ -46,47 +46,50 @@ def require_all(path) require_all 'jekyll/tags' module Jekyll - VERSION = '0.11.2' + VERSION = '0.12.0' # Default options. Overriden by values in _config.yml or command-line opts. - # (Strings rather symbols used for compatability with YAML). + # Strings rather than symbols are used for compatability with YAML. DEFAULTS = { 'safe' => false, 'auto' => false, 'server' => false, 'server_port' => 4000, - 'source' => Dir.pwd, - 'destination' => File.join(Dir.pwd, '_site'), - 'plugins' => File.join(Dir.pwd, '_plugins'), + 'source' => Dir.pwd, + 'destination' => File.join(Dir.pwd, '_site'), + 'plugins' => File.join(Dir.pwd, '_plugins'), + 'layouts' => '_layouts', 'keep_files' => ['.git','.svn'], - 'layouts' => '_layouts', - - 'future' => true, - 'lsi' => false, - 'pygments' => false, - 'markdown' => 'maruku', - 'permalink' => 'date', - 'include' => ['.htaccess'], + + 'future' => true, + 'lsi' => false, + 'pygments' => false, + 'markdown' => 'maruku', + 'permalink' => 'date', + 'include' => ['.htaccess'], 'paginate_path' => 'page:num', - 'markdown_ext' => 'markdown,mkd,mkdn,md', - 'textile_ext' => 'textile', + 'markdown_ext' => 'markdown,mkd,mkdn,md', + 'textile_ext' => 'textile', - 'maruku' => { + 'maruku' => { 'use_tex' => false, 'use_divs' => false, 'png_engine' => 'blahtex', 'png_dir' => 'images/latex', 'png_url' => '/images/latex' }, - 'rdiscount' => { + + 'rdiscount' => { 'extensions' => [] }, - 'redcarpet' => { + + 'redcarpet' => { 'extensions' => [] }, - 'kramdown' => { + + 'kramdown' => { 'auto_ids' => true, 'footnote_nr' => 1, 'entity_output' => 'as_char', @@ -103,8 +106,9 @@ module Jekyll 'coderay_css' => 'style' } }, - 'redcloth' => { - 'hard_breaks' => true + + 'redcloth' => { + 'hard_breaks' => true } } diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index cb94c8d098f..3c6ba5399da 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -8,12 +8,28 @@ class MarkdownConverter < Converter def setup return if @setup - # Set the Markdown interpreter (and Maruku self.config, if necessary) case @config['markdown'] when 'redcarpet' begin require 'redcarpet' - @redcarpet_extensions = @config['redcarpet']['extensions'].map { |e| e.to_sym } + + @renderer ||= Class.new(Redcarpet::Render::HTML) do + def block_code(code, lang) + lang = lang && lang.split.first || "text" + output = add_code_tags( + Pygments.highlight(code, :lexer => lang, :options => { :encoding => 'utf-8' }), + lang + ) + end + + def add_code_tags(code, lang) + code = code.sub(/
/,'
')
+                code = code.sub(/<\/pre>/,"
")
+              end
+            end
+
+            @redcarpet_extensions = {}
+            @config['redcarpet']['extensions'].each { |e| @redcarpet_extensions[e.to_sym] = true }
           rescue LoadError
             STDERR.puts 'You are missing a library required for Markdown. Please run:'
             STDERR.puts '  $ [sudo] gem install redcarpet'
@@ -30,8 +46,6 @@ def setup
         when 'rdiscount'
           begin
             require 'rdiscount'
-
-            # Load rdiscount extensions
             @rdiscount_extensions = @config['rdiscount']['extensions'].map { |e| e.to_sym }
           rescue LoadError
             STDERR.puts 'You are missing a library required for Markdown. Please run:'
@@ -88,7 +102,10 @@ def convert(content)
       setup
       case @config['markdown']
         when 'redcarpet'
-          Redcarpet.new(content, *@redcarpet_extensions).to_html
+          @redcarpet_extensions[:fenced_code_blocks] = !@redcarpet_extensions[:no_fenced_code_blocks]
+          @renderer.send :include, Redcarpet::Render::SmartyPants if @redcarpet_extensions[:smart]
+          markdown = Redcarpet::Markdown.new(@renderer.new(@redcarpet_extensions), @redcarpet_extensions)
+          markdown.render(content)
         when 'kramdown'
           # Check for use of coderay
           if @config['kramdown']['use_coderay']
diff --git a/lib/jekyll/convertible.rb b/lib/jekyll/convertible.rb
index fe25b30e610..e71fe1bf8ef 100644
--- a/lib/jekyll/convertible.rb
+++ b/lib/jekyll/convertible.rb
@@ -25,15 +25,17 @@ def to_s
     #
     # Returns nothing.
     def read_yaml(base, name)
-      self.content = File.read(File.join(base, name))
-
       begin
-        if self.content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
+        self.content = File.read(File.join(base, name))
+
+        if self.content =~ /\A(---\s*\n.*?\n?)^(---\s*$\n?)/m
           self.content = $POSTMATCH
           self.data = YAML.load($1)
         end
       rescue => e
-        puts "YAML Exception reading #{name}: #{e.message}"
+        puts "Error reading file #{File.join(base, name)}: #{e.message}"
+      rescue SyntaxError => e
+        puts "YAML Exception reading #{File.join(base, name)}: #{e.message}"
       end
 
       self.data ||= {}
@@ -76,9 +78,13 @@ def do_layout(payload, layouts)
       payload["pygments_suffix"] = converter.pygments_suffix
 
       begin
-        self.content = Liquid::Template.parse(self.content).render(payload, info)
+        self.content = Liquid::Template.parse(self.content).render!(payload, info)
       rescue => e
         puts "Liquid Exception: #{e.message} in #{self.name}"
+        e.backtrace.each do |backtrace|
+          puts backtrace
+        end
+        abort("Build Failed")
       end
 
       self.transform
@@ -94,9 +100,13 @@ def do_layout(payload, layouts)
         payload = payload.deep_merge({"content" => self.output, "page" => layout.data})
 
         begin
-          self.output = Liquid::Template.parse(layout.content).render(payload, info)
+          self.output = Liquid::Template.parse(layout.content).render!(payload, info)
         rescue => e
           puts "Liquid Exception: #{e.message} in #{self.data["layout"]}"
+          e.backtrace.each do |backtrace|
+            puts backtrace
+          end
+          abort("Build Failed")
         end
 
         if layout = layouts[layout.data["layout"]]
diff --git a/lib/jekyll/filters.rb b/lib/jekyll/filters.rb
index eb61d84a239..0012c25f433 100644
--- a/lib/jekyll/filters.rb
+++ b/lib/jekyll/filters.rb
@@ -57,6 +57,17 @@ def date_to_xmlschema(date)
       date.xmlschema
     end
 
+    # XML escape a string for use. Replaces any special characters with
+    # appropriate HTML entity replacements.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   xml_escape('foo "bar" ')
+    #   # => "foo "bar" <baz>"
+    #
+    # Returns the escaped String.
     def xml_escape(input)
       CGI.escapeHTML(input)
     end
diff --git a/lib/jekyll/migrators/posterous.rb b/lib/jekyll/migrators/posterous.rb
index 0a2280f255e..f1601ba3638 100644
--- a/lib/jekyll/migrators/posterous.rb
+++ b/lib/jekyll/migrators/posterous.rb
@@ -1,11 +1,14 @@
 require 'rubygems'
 require 'jekyll'
 require 'fileutils'
-require 'net/http'
+require 'net/https'
+require 'open-uri'
 require 'uri'
 require "json"
 
-# ruby -r './lib/jekyll/migrators/posterous.rb' -e 'Jekyll::Posterous.process(email, pass, api_key, blog)'
+# ruby -r './lib/jekyll/migrators/posterous.rb' -e 'Jekyll::Posterous.process(email, pass, api_token, blog, tags_key)'
+# You can find your api token in posterous api page - http://posterous.com/api . Click on any of the 'view token' links to see your token.
+# blog is optional, by default it is the primary one
 
 module Jekyll
   module Posterous
@@ -14,6 +17,9 @@ def self.fetch(uri_str, limit = 10)
       raise ArgumentError, 'Stuck in a redirect loop. Please double check your email and password' if limit == 0
 
       response = nil
+
+      puts uri_str
+      puts '-------'
       Net::HTTP.start('posterous.com') do |http|
         req = Net::HTTP::Get.new(uri_str)
         req.basic_auth @email, @pass
@@ -23,36 +29,50 @@ def self.fetch(uri_str, limit = 10)
       case response
         when Net::HTTPSuccess     then response
         when Net::HTTPRedirection then fetch(response['location'], limit - 1)
+        when Net::HTTPForbidden   then
+          retry_after = response.to_hash['retry-after'][0]
+          puts "We have been told to try again after #{retry_after} seconds"
+          sleep(retry_after.to_i + 1)
+          fetch(uri_str, limit - 1)
         else response.error!
       end
     end
 
-    def self.process(email, pass, api_token, blog = 'primary')
+    def self.process(email, pass, api_token, blog = 'primary', tags_key = 'categories')
       @email, @pass, @api_token = email, pass, api_token
       FileUtils.mkdir_p "_posts"
 
-      posts = JSON.parse(self.fetch("/api/v2/users/me/sites/#{blog}/posts?api_token=#{@api_token}").body)
+      posts = JSON.parse(self.fetch("/api/2/sites/#{blog}/posts?api_token=#{@api_token}").body)
       page = 1
 
       while posts.any?
         posts.each do |post|
           title = post["title"]
-          slug = title.gsub(/[^[:alnum:]]+/, '-').downcase
+          slug = title.gsub(/[^[:alnum:]]+/, '-').gsub(/^-+|-+$/, '').downcase
+          posterous_slug = post["slug"]
           date = Date.parse(post["display_date"])
           content = post["body_html"]
           published = !post["is_private"]
           name = "%02d-%02d-%02d-%s.html" % [date.year, date.month, date.day, slug]
+          tags = []
+          post["tags"].each do |tag|
+            tags.push(tag["name"])
+          end
 
           # Get the relevant fields as a hash, delete empty fields and convert
           # to YAML for the header
           data = {
              'layout' => 'post',
              'title' => title.to_s,
-             'published' => published
+             'published' => published,
+             tags_key => tags,
+             'posterous_url' => post["full_url"],
+             'posterous_slug' => posterous_slug
            }.delete_if { |k,v| v.nil? || v == ''}.to_yaml
 
           # Write out the data and content to file
           File.open("_posts/#{name}", "w") do |f|
+            puts name
             f.puts data
             f.puts "---"
             f.puts content
@@ -60,7 +80,7 @@ def self.process(email, pass, api_token, blog = 'primary')
         end
 
         page += 1
-        posts = JSON.parse(self.fetch("/api/v2/users/me/sites/#{blog}/posts?api_token=#{@api_token}&page=#{page}").body)
+        posts = JSON.parse(self.fetch("/api/2/sites/#{blog}/posts?api_token=#{@api_token}&page=#{page}").body)
       end
     end
   end
diff --git a/lib/jekyll/post.rb b/lib/jekyll/post.rb
index a84c9ab97d3..a360cb8de58 100644
--- a/lib/jekyll/post.rb
+++ b/lib/jekyll/post.rb
@@ -8,12 +8,13 @@ class << self
       attr_accessor :lsi
     end
 
+    # Valid post name regex.
     MATCHER = /^(.+\/)*(\d+-\d+-\d+)-(.*)(\.[^.]+)$/
 
     # Post name validator. Post filenames must be like:
-    #   2008-11-05-my-awesome-post.textile
+    # 2008-11-05-my-awesome-post.textile
     #
-    # Returns 
+    # Returns true if valid, false if not.
     def self.valid?(name)
       name =~ MATCHER
     end
@@ -25,12 +26,13 @@ def self.valid?(name)
     attr_reader :name
 
     # Initialize this Post instance.
-    #   +site+ is the Site
-    #   +base+ is the String path to the dir containing the post file
-    #   +name+ is the String filename of the post file
-    #   +categories+ is an Array of Strings for the categories for this post
     #
-    # Returns 
+    # site       - The Site.
+    # base       - The String path to the dir containing the post file.
+    # name       - The String filename of the post file.
+    # categories - An Array of Strings for the categories for this post.
+    #
+    # Returns the new Post.
     def initialize(site, source, dir, name)
       @site = site
       @base = File.join(source, dir, '_posts')
@@ -38,10 +40,14 @@ def initialize(site, source, dir, name)
 
       self.categories = dir.split('/').reject { |x| x.empty? }
       self.process(name)
-      self.read_yaml(@base, name)
+      begin 
+        self.read_yaml(@base, name)
+      rescue Exception => msg
+        raise FatalException.new("#{msg} in #{@base}/#{name}")
+      end
 
-      #If we've added a date and time to the yaml, use that instead of the filename date
-      #Means we'll sort correctly.
+      # If we've added a date and time to the YAML, use that instead of the
+      # filename date. Means we'll sort correctly.
       if self.data.has_key?('date')
         # ensure Time via to_s and reparse
         self.date = Time.parse(self.data["date"].to_s)
@@ -60,7 +66,10 @@ def initialize(site, source, dir, name)
       end
     end
 
-    # Spaceship is based on Post#date, slug
+    # Compares Post objects. First compares the Post date. If the dates are
+    # equal, it compares the Post slugs.
+    #
+    # other - The other Post we are comparing to.
     #
     # Returns -1, 0, 1
     def <=>(other)
@@ -71,10 +80,11 @@ def <=>(other)
       return cmp
     end
 
-    # Extract information from the post filename
-    #   +name+ is the String filename of the post file
+    # Extract information from the post filename.
+    #
+    # name - The String filename of the post file.
     #
-    # Returns nothing
+    # Returns nothing.
     def process(name)
       m, cats, date, slug, ext = *name.match(MATCHER)
       self.date = Time.parse(date)
@@ -87,18 +97,17 @@ def process(name)
     # The generated directory into which the post will be placed
     # upon generation. This is derived from the permalink or, if
     # permalink is absent, set to the default date
-    # e.g. "/2008/11/05/" if the permalink style is :date, otherwise nothing
+    # e.g. "/2008/11/05/" if the permalink style is :date, otherwise nothing.
     #
-    # Returns 
+    # Returns the String directory.
     def dir
       File.dirname(url)
     end
 
-    # The full path and filename of the post.
-    # Defined in the YAML of the post body
-    # (Optional)
+    # The full path and filename of the post. Defined in the YAML of the post
+    # body (optional).
     #
-    # Returns 
+    # Returns the String permalink.
     def permalink
       self.data && self.data['permalink']
     end
@@ -116,10 +125,10 @@ def template
       end
     end
 
-    # The generated relative url of this post
+    # The generated relative url of this post.
     # e.g. /2008/11/05/my-awesome-post.html
     #
-    # Returns 
+    # Returns the String URL.
     def url
       return @url if @url
 
@@ -146,17 +155,17 @@ def url
       @url
     end
 
-    # The UID for this post (useful in feeds)
+    # The UID for this post (useful in feeds).
     # e.g. /2008/11/05/my-awesome-post
     #
-    # Returns 
+    # Returns the String UID.
     def id
       File.join(self.dir, self.slug)
     end
 
     # Calculate related posts.
     #
-    # Returns []
+    # Returns an Array of related Posts.
     def related_posts(posts)
       return [] unless posts.size > 1
 
@@ -176,11 +185,12 @@ def related_posts(posts)
       end
     end
 
-    # Add any necessary layouts to this post
-    #   +layouts+ is a Hash of {"name" => "layout"}
-    #   +site_payload+ is the site payload hash
+    # Add any necessary layouts to this post.
     #
-    # Returns nothing
+    # layouts      - A Hash of {"name" => "layout"}.
+    # site_payload - The site payload hash.
+    #
+    # Returns nothing.
     def render(layouts, site_payload)
       # construct payload
       payload = {
@@ -192,9 +202,10 @@ def render(layouts, site_payload)
     end
     
     # Obtain destination path.
-    #   +dest+ is the String path to the destination dir
     #
-    # Returns destination file path.
+    # dest - The String path to the destination dir.
+    #
+    # Returns destination file path String.
     def destination(dest)
       # The url needs to be unescaped in order to preserve the correct filename
       path = File.join(dest, CGI.unescape(self.url))
@@ -203,9 +214,10 @@ def destination(dest)
     end
 
     # Write the generated post file to the destination directory.
-    #   +dest+ is the String path to the destination dir
     #
-    # Returns nothing
+    # dest - The String path to the destination dir.
+    #
+    # Returns nothing.
     def write(dest)
       path = destination(dest)
       FileUtils.mkdir_p(File.dirname(path))
@@ -216,7 +228,7 @@ def write(dest)
 
     # Convert this post into a Hash for use in Liquid templates.
     #
-    # Returns 
+    # Returns the representative Hash.
     def to_liquid
       self.data.deep_merge({
         "title"      => self.data["title"] || self.slug.split('-').select {|w| w.capitalize! || w }.join(' '),
@@ -230,6 +242,7 @@ def to_liquid
         "content"    => self.content })
     end
 
+    # Returns the shorthand String identifier of this Post.
     def inspect
       ""
     end
diff --git a/lib/jekyll/site.rb b/lib/jekyll/site.rb
index d8b729f97bc..6afa3c9e57b 100644
--- a/lib/jekyll/site.rb
+++ b/lib/jekyll/site.rb
@@ -72,6 +72,12 @@ def reset
     def setup
       require 'classifier' if self.lsi
 
+      # Check that the destination dir isn't the source dir or a directory
+      # parent to the source dir.
+      if self.source =~ /^#{self.dest}/
+        raise FatalException.new "Destination directory cannot be or contain the Source directory."
+      end
+
       # If safe mode is off, load in any Ruby files under the plugins
       # directory.
       unless self.safe
@@ -244,7 +250,6 @@ def cleanup
       files.merge(dirs)
 
       obsolete_files = dest_files - files
-
       FileUtils.rm_rf(obsolete_files.to_a)
     end
 
@@ -329,7 +334,7 @@ def site_payload
     #
     # Returns the Array of filtered entries.
     def filter_entries(entries)
-      entries = entries.reject do |e|
+      entries.reject do |e|
         unless self.include.include?(e)
           ['.', '_', '#'].include?(e[0..0]) ||
           e[-1..-1] == '~' ||
diff --git a/site/.gitignore b/site/.gitignore
new file mode 100644
index 00000000000..79bd74f7496
--- /dev/null
+++ b/site/.gitignore
@@ -0,0 +1,4 @@
+_site/
+*.swp
+pkg/
+test/
diff --git a/site/CNAME b/site/CNAME
new file mode 100644
index 00000000000..f501cdec1ba
--- /dev/null
+++ b/site/CNAME
@@ -0,0 +1 @@
+jekyllrb.com
diff --git a/site/README b/site/README
new file mode 100644
index 00000000000..60b411cb620
--- /dev/null
+++ b/site/README
@@ -0,0 +1 @@
+Jekyll's awesome website.
diff --git a/site/_config.yml b/site/_config.yml
new file mode 100644
index 00000000000..79be19f5c06
--- /dev/null
+++ b/site/_config.yml
@@ -0,0 +1,5 @@
+auto: false
+server: true
+permalink: /docs/:categories/:title
+pygments: true
+gauges_id: 503c5af6613f5d0f19000027
diff --git a/site/_includes/analytics.html b/site/_includes/analytics.html
new file mode 100644
index 00000000000..bbdc351ecc6
--- /dev/null
+++ b/site/_includes/analytics.html
@@ -0,0 +1,32 @@
+{% if site.gauges_id %}
+  
+  
+{% endif %}
+
+{% if site.google_analytics_id %}
+  
+  
+{% endif %}
diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html
new file mode 100644
index 00000000000..ad3f3e167f4
--- /dev/null
+++ b/site/_includes/docs_contents.html
@@ -0,0 +1,79 @@
+

+  
+

diff --git a/site/_includes/footer.html b/site/_includes/footer.html
new file mode 100644
index 00000000000..b0c084dc7af
--- /dev/null
+++ b/site/_includes/footer.html
@@ -0,0 +1,15 @@
+
+

diff --git a/site/_includes/header.html b/site/_includes/header.html
new file mode 100644
index 00000000000..70ba591d9d6
--- /dev/null
+++ b/site/_includes/header.html
@@ -0,0 +1,26 @@
+

+  

+    

+      

+        
+          Jekyll
+          
+        
+      

+    

+    
+    

+  

+

diff --git a/site/_includes/section_nav.html b/site/_includes/section_nav.html
new file mode 100644
index 00000000000..14ae1d2ccb0
--- /dev/null
+++ b/site/_includes/section_nav.html
@@ -0,0 +1,22 @@
+

+  

+    {% if page.prev_section != null %}
+      
+    {% else %}
+      Back
+    {% endif %}
+  

+  

+    {% if page.next_section != null %}
+      
+    {% else %}
+      Next
+    {% endif %}
+  

+  

+

+
diff --git a/site/_includes/top.html b/site/_includes/top.html
new file mode 100644
index 00000000000..6ee24730631
--- /dev/null
+++ b/site/_includes/top.html
@@ -0,0 +1,14 @@
+
+
+
+  
+  {{ page.title }}
+  
+  
+  
+  
+  
+  
+  
+  
+
diff --git a/site/_layouts/default.html b/site/_layouts/default.html
new file mode 100644
index 00000000000..80c9e4c1dcd
--- /dev/null
+++ b/site/_layouts/default.html
@@ -0,0 +1,12 @@
+{% include top.html %}
+
+
+  {% include header.html %}
+
+  {{ content }}
+
+  {% include footer.html %}
+  {% include analytics.html %}
+
+
+
diff --git a/site/_layouts/docs.html b/site/_layouts/docs.html
new file mode 100644
index 00000000000..b88f7a584c0
--- /dev/null
+++ b/site/_layouts/docs.html
@@ -0,0 +1,21 @@
+---
+layout: default
+---
+
+  

+    

+
+      

+        

+          
{{ page.title }}

+          {{ content }}
+          {% include section_nav.html %}
+        

+      

+
+      {% include docs_contents.html %}
+
+      

+
+    

+  

diff --git a/site/_posts/2012-07-01-configuration.md b/site/_posts/2012-07-01-configuration.md
new file mode 100644
index 00000000000..a942914b1c2
--- /dev/null
+++ b/site/_posts/2012-07-01-configuration.md
@@ -0,0 +1,250 @@
+---
+layout: docs
+title: Configuration
+prev_section: structure
+next_section: frontmatter
+---
+
+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
+
+The table below lists the available settings for Jekyll, and the various options (specifed in the configuration file) and flags (specified on the command-line) that control them.
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+
+  
+
SettingOptions and Flags

+        
Safe

+        
Disables custom plugins.

+      		
+        
safe: [boolean]

+        
--safe

+      

+        
Regeneration

+        
Enables or disables Jekyll from recreating the site when files are modified.

+      		
+        
auto: [boolean]

+        
--auto

+        
--no-auto

+      

+        
Local Server

+        
Fires up a server that will host your _site directory

+      		
+        
server: [boolean]

+        
--server

+      

+        
Local Server Port

+        
Changes the port that the Jekyll server will run on

+      		
+        
server_port: [integer]

+        
--server [port]

+      

+        
Base URL

+        
Serve website from a given base URL

+      		
+        
baseurl: [BASE_URL]

+        
--base-url [url]

+      

+        
URL

+        
Sets site.url, useful for environment switching

+      		
+        
url: [URL]

+        
--url [URL]

+      

+        
Site Destination

+        
Changes the directory where Jekyll will write files to

+      		
+        
destination: [dir]

+        
jekyll [dest]

+      

+        
Site Source

+        
Changes the directory where Jekyll will look to transform files

+      		
+        
source: [dir]

+        
jekyll [source] [dest]

+      

+        
Markdown

+        
Uses RDiscount or [engine] instead of Maruku.

+      		
+        
markdown: [engine]

+        
--rdiscount

+        
--kramdown

+        
--redcarpet

+      

+        
Pygments

+        
Enables highlight tag with Pygments.

+      		
+        
pygments: [boolean]

+        
--pygments

+      

+        
Future

+        
Publishes posts with a future date

+      		
+        
future: [boolean]

+        
--no-future

+        
--future

+      

+        
LSI

+        
Produces an index for related posts.

+      		
+        
lsi: [boolean]

+        
--lsi

+      

+        
Permalink

+        
Controls the URLs that posts are generated with. Please refer to the Permalinks page for more info.

+      		
+        
permalink: [style]

+        
--permalink=[style]

+      

+        
Pagination

+        
Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"

+      		
+        
paginate: [per_page]

+        
--paginate [per_page]

+      

+        
Exclude

+        
A list of directories and files to exclude from the conversion

+      		
+        
exclude: [dir1, file1, dir2]

+      

+        
Include

+        
A list of directories and files to specifically include in the conversion. .htaccess is a good example since dotfiles are excluded by default.

+      		
+        
include: [dir1, file1, dir2]

+      

+        
Limit Posts

+        
Limits the number of posts to parse and publish

+      		
+        
limit_posts: [max_posts]

+        
--limit_posts=[max_posts]

+      

+
+

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

+

+
+## 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.
+
+{% highlight yaml %}
+safe:        false
+auto:        false
+server:      false
+server_port: 4000
+baseurl:     /
+url:         http://localhost:4000
+
+source:      .
+destination: ./_site
+plugins:     ./_plugins
+
+future:      true
+lsi:         false
+pygments:    false
+markdown:    maruku
+permalink:   date
+
+maruku:
+  use_tex:    false
+  use_divs:   false
+  png_engine: blahtex
+  png_dir:    images/latex
+  png_url:    /images/latex
+
+rdiscount:
+  extensions: []
+
+kramdown:
+  auto_ids: true,
+  footnote_nr: 1
+  entity_output: as_char
+  toc_levels: 1..6
+  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
+
+{% endhighlight %}
diff --git a/site/_posts/2012-07-01-contributing.md b/site/_posts/2012-07-01-contributing.md
new file mode 100644
index 00000000000..80e625b1395
--- /dev/null
+++ b/site/_posts/2012-07-01-contributing.md
@@ -0,0 +1,66 @@
+---
+layout: docs
+title: Contributing
+prev_section: deployment-methods
+next_section: troubleshooting
+---
+
+Contributions to Jekyll are always welcome, however there’s a few things that you should keep in mind to improve your chances of having your changes merged in.
+
+## Workflow
+
+Here’s the most typical way to get your change merged into the project:
+
+1. Fork the project [on GitHub](https://github.com/mojombo/jekyll) and clone it down to your local machine.
+2. Create a topic branch to contain your change.
+3. Hack away, add tests. Not necessarily in that order.
+4. Make sure all the existing tests still pass.
+5. If necessary, rebase your commits into logical chunks, without errors.
+6. Push the branch up to your fork on GitHub.
+7. Create an issue on GitHub with a link to your branch.
+
+

+  
Contributions will not be accepted without tests

+  
If you’re creating a small fix or patch to an existing feature, just
+    a simple test will do.

+

+
+## Tests
+
+We’re big on tests, so please be sure to include them. Please stay in the confines of the current test suite and use [Shoulda](https://github.com/thoughtbot/shoulda) and [RR](https://github.com/btakita/rr).
+
+### Tests for brand-new features
+
+If it’s a brand new feature, make sure to create a new [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps where appropriate. Also, whipping up some documentation in your fork’s `gh-pages` branch would be appreciated, so the main website can be updated as soon as your new feature is merged.
+
+### Test dependencies
+
+To run the test suite and build the gem you’ll need to install Jekyll’s dependencies. Jekyll uses Bundler, so a quick run of the bundle command and you’re all set!
+
+{% highlight bash %}
+$ bundle
+{% endhighlight %}
+
+Before you start, run the tests and make sure that they pass (to confirm
+your environment is configured properly):
+
+{% highlight bash %}
+$ rake test
+$ rake features
+{% endhighlight %}
+
+## Common Gotchas
+
+- If you want to bump the gem version, please put that in a separate
+  commit. This way, the maintainers can control when the gem gets released.
+- Try to keep your patch(es) based from [the latest commit on
+  mojombo/jekyll](https://github.com/mojombo/jekyll/commits/master). The easier it is to apply your work, the less work
+  the maintainers have to do, which is always a good thing.
+- Please don’t tag your GitHub issue with labels like “fix” or “feature”.
+  The maintainers actively read the issues and will label it once they come
+  across it.
+
+

+  
Let us know what could be better!

+  
Both using and hacking on Jekyll should be fun, simple, and easy, so if for some reason you find it’s a pain, please create an issue on GitHub describing your experience so we can make it better.

+

diff --git a/site/_posts/2012-07-01-deployment-methods.md b/site/_posts/2012-07-01-deployment-methods.md
new file mode 100644
index 00000000000..7716e5f8ccc
--- /dev/null
+++ b/site/_posts/2012-07-01-deployment-methods.md
@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Deployment methods
+prev_section: github-pages
+next_section: contributing
+---
+
+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.
+
+## Web hosting providers (FTP)
+
+Just about any traditional web hosting provider will let you upload files to their servers over FTP. To upload a Jekyll site to a web host using FTP, simply run the `jekyll` command and copy the generated `_site` folder to the root folder of your hosting account. This is most likely to be the `httpdocs` or `public_html` folder on most hosting providers.
+
+### FTP using Glynn
+
+There is a project called [Glynn](https://github.com/dmathieu/glynn), which lets you easily generate your Jekyll powered website’s static files and
+send them to your host through FTP.
+
+## Self-managed web server
+
+If you have direct access yourself to the deployment web server yourself, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Just remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
+
+## Automated methods
+
+There are also a number of ways to easily automate the deployment of a Jekyll site. If you’ve got another method that isn’t listed below, we’d love it if you [contributed](../contributing) so that everyone else can benefit too.
+
+### Git post-update hook
+
+If you store your jekyll site in [Git](http://git-scm.com/) (you are using version control, right?), it’s pretty easy to automate the
+deployment process by setting up a post-update hook in your Git
+repository, [like
+this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/03/26/deploying-a-jekyll-generated-site/).
+
+### Git post-receive hook
+
+To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows:
+
+{% highlight bash %}
+laptop$ ssh deployer@myserver.com
+server$ mkdir myrepo.git
+server$ cd myrepo.git
+server$ git --bare init
+server$ cp hooks/post-receive.sample hooks/post-receive
+server$ mkdir /var/www/myrepo
+{% endhighlight %}
+
+Next, add the following lines to hooks/post-receive and be sure Jekyll is
+installed on the server:
+
+{% highlight bash %}
+GIT_REPO=$HOME/myrepo.git
+TMP_GIT_CLONE=$HOME/tmp/myrepo
+PUBLIC_WWW=/var/www/myrepo
+
+git clone $GIT_REPO $TMP_GIT_CLONE
+jekyll --no-auto $TMP_GIT_CLONE $PUBLIC_WWW
+rm -Rf $TMP_GIT_CLONE
+exit
+{% endhighlight %}
+
+Finally, run the following command on any users laptop that needs to be able to
+deploy using this hook:
+
+{% highlight bash %}
+laptops$ git remote add deploy deployer@myserver.com:~/myrepo.git
+{% endhighlight %}
+
+Deploying is now as easy as telling nginx or Apache to look at
+`/var/www/myrepo` and running the following:
+
+{% highlight bash %}
+laptops$ git push deploy master
+{% endhighlight %}
+
+### Rake
+
+Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimweirich/rake), [HighLine](https://github.com/JEG2/highline), and
+[Net::SSH](http://net-ssh.rubyforge.org/). A more complex example of deploying Jekyll with Rake that deals with multiple branches can be found in [Git Ready](https://github.com/gitready/gitready/blob/en/Rakefile).
+
+### rsync
+
+Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](http://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
+this script from within Textmate.
+
+
+## Rack-Jekyll
+
+[Rack-Jekyll](http://github.com/bry4n/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](http://github.com/rtomakyo/shotgun/), [rackup](http://github.com/rack/rack), [mongrel](http://github.com/mongrel/mongrel), [unicorn](http://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
+
+Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
+
+## Jekyll-Admin for Rails
+
+If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](http://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](http://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
+
+## Amazon S3
+
+If you want to host your site in Amazon S3, you can do so with
+[jekyll-s3](https://github.com/laurilehmijoki/jekyll-s3) application. It will
+push your site to Amazon S3 where it can be served like any web server,
+dynamically scaling to almost unlimited traffic. This approach has the
+benefit of being about the cheapest hosting option available for
+low-volume blogs as you only pay for what you use.
+
+

+  
ProTip™: Use GitHub Pages for zero-hassle Jekyll hosting

+  
GitHub Pages are powered by Jekyll behind the scenes, so if you’re looking for a zero-hassle, zero-cost solution, GitHub Pages are a great way to host your Jekyll-powered website for free.

+

diff --git a/site/_posts/2012-07-01-extras.md b/site/_posts/2012-07-01-extras.md
new file mode 100644
index 00000000000..1af24d106ca
--- /dev/null
+++ b/site/_posts/2012-07-01-extras.md
@@ -0,0 +1,103 @@
+---
+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 `{{ "{% highlight " }}%}` tag in your
+posts, you’ll need to install [Pygments](http://pygments.org/).
+
+### Installing Pygments on OSX
+
+Mac OS X (Leopard onwards) come 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}"
+easy_install pip
+pip install --upgrade distribute
+pip install pygments
+{% endhighlight %}
+
+**ProTip™**: 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 [the Homebrew wiki](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python).
+
+#### 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 run Jekyll with the following option:
+
+{% highlight bash %}
+jekyll --rdiscount
+{% endhighlight %}
+
+Or, specify RDiscount as the markdown engine in your `_config.yml` file to have Jekyll run with that option by default (so you don’t have to specify the flag every time).
+
+{% highlight bash %}
+# In _config.yml
+markdown: rdiscount
+{% endhighlight %}
+
diff --git a/site/_posts/2012-07-01-frontmatter.md b/site/_posts/2012-07-01-frontmatter.md
new file mode 100644
index 00000000000..982e5ec10b2
--- /dev/null
+++ b/site/_posts/2012-07-01-frontmatter.md
@@ -0,0 +1,120 @@
+---
+layout: docs
+title: Front-matter
+prev_section: configuration
+next_section: posts
+---
+
+The front-matter is where Jekyll starts to get really cool. Any files that contain a [YAML](http://yaml.org/) front matter block will be processed by Jekyll as special files. The front matter must be the first thing in the file and must take the form of sets of variables and values set between triple-dashed lines. Here is a basic example:
+
+{% highlight yaml %}
+---
+layout: post
+title: Blogging Like a Hacker
+---
+{% endhighlight %}
+
+Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.
+
+

+  
UTF-8 Character Encoding Warning

+  
If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running Jekyll on Windows.

+

+
+## Predefined Global Variables
+
+There are a number of predefined global variables that you can set in the front-matter of a page or post.
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
VariableDescription

+        
layout

+      		
+        
If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the _layouts directory.

+      

+        
permalink

+      		
+        
If you need your processed URLs to be something other than the default /year/month/day/title.html then you can set this variable and it will be used as the final URL.

+      

+        
published

+      		
+        
Set to false if you don’t want a post to show up when the site is generated.

+      

+        
category

+        
categories

+      		
+        
Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a YAML list or a space-separated string.

+      

+        
tags

+      		
+        
Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.

+      

+
+
+## Custom Variables
+
+Any variables in the front matter that are not predefined are mixed into
+the data that is sent to the Liquid templating engine during the
+conversion. For instance, if you set a title, you can use that in your
+layout to set the page title:
+
+{% highlight html %}
+
+
+  
+    {{ "{{ page.title " }}}}
+  
+  
+    ...
+{% endhighlight %}
+
+## Predefined Variables for Posts
+
+These are available out-of-the-box to be used in the front-matter for a
+post.
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
VariableDescription

+        
date

+      		
+        
A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.

+      

diff --git a/site/_posts/2012-07-01-github-pages.md b/site/_posts/2012-07-01-github-pages.md
new file mode 100644
index 00000000000..dbe8434a4f6
--- /dev/null
+++ b/site/_posts/2012-07-01-github-pages.md
@@ -0,0 +1,34 @@
+---
+layout: docs
+title: GitHub Pages
+prev_section: extras
+next_section: deployment-methods
+---
+
+[GitHub Pages](https://pages.github.com) are public web pages for users, organizations, and repositories, that are freely hosted on [GitHub](https://github.com/). GitHub Pages are powered by Jekyll behind the scenes, so in addition to supporting regular HTML content, they’re also a great way to host your Jekyll-powered website for free.
+
+## Deploying Jekyll to GitHub Pages
+
+GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types of Pages available, user/organization Pages and project Pages. The way to deploy these two types of pages are nearly identical, except for a few minor details.
+
+### User and Organization Pages
+
+User and organization Pages live in a special GitHub repository dedicated to only the Pages files. This repository must be named after the account name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.com) has the name `mojombo.github.com`.
+
+Content from the `master` branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.
+
+

+  
Custom domains do not affect repository names

+  
GitHub Pages are initially configured to live under the `username.github.com` subdomain, which is why repositories must be named this way even if a custom domain is being used.

+

+
+### Project Pages
+
+Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named `gh-pages` branch. The content of this branch will be used to rendered using Jekyll, and the output will become available under a subpath of your user pages subdomain, such as `username.github.com/project` (unless a custom domain is specified—see below).
+
+The Jekyll project repository itself is a perfect example of this branch structure—the [master branch](https://github.com/mojombo/jekyll) contains the actual software project for Jekyll, however the Jekyll website (that you’re looking at right now) is contained in the [gh-pages branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
+
+

+  
GitHub Pages Documentation, Help, and Support

+  
For more information about what you can do with GitHub Pages, as well as for troubleshooting guides, you should check out GitHub’s Pages Help section. If all else fails, you should contact GitHub Support.

+

diff --git a/site/_posts/2012-07-01-heroku.md b/site/_posts/2012-07-01-heroku.md
new file mode 100644
index 00000000000..091239c5209
--- /dev/null
+++ b/site/_posts/2012-07-01-heroku.md
@@ -0,0 +1,8 @@
+---
+layout: docs
+title: Heroku
+prev_section: github-pages
+next_section: manual-deployment
+---
+
+Move along, people. Nothing to see here.
diff --git a/site/_posts/2012-07-01-home.md b/site/_posts/2012-07-01-home.md
new file mode 100644
index 00000000000..9c27eeefcda
--- /dev/null
+++ b/site/_posts/2012-07-01-home.md
@@ -0,0 +1,47 @@
+---
+layout: docs
+title: Welcome
+next_section: installation
+---
+
+This site aims to be a comprehensive guide to Jekyll. We’ll cover everything from getting your site up and running, creating and managing your content, customizing the way your site works and looks, deploying to various environments, as well as some advice on participating in the future development of Jekyll itself.
+
+## So what is Jekyll, exactly?
+
+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/) 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 to host your project’s page, blog, or website from GitHub’s servers **for free**.
+
+## Quick-start guide
+
+For the impatient, here's how to get Jekyll up and running.
+
+{% highlight bash %}
+~ $ gem install jekyll
+~ $ mkdir -p my/new/site
+~ $ cd my/new/site
+~ $ vim index.html
+~/my/new/site $ jekyll --server
+# => Now browse to http://localhost:4000
+{% endhighlight %}
+
+That's nothing though. The real magic happens when you start creating posts, using the front-matter to conrol templates and layouts, and taking advantage of all the awesome configuration options Jekyll makes available.
+
+## ProTips™, Notes, and Warnings
+
+Throughout this guide there are a number of small-but-handy pieces of information that can make using Jekyll easier, more interesting, and less hazardous. Here’s what to look out for.
+
+

+  
ProTips™ help you get more from Jekyll

+  
These are tips and tricks that will help you be a Jekyll wizard!

+

+
+

+  
Notes are handy pieces of information

+  
These are for the extra tidbits sometimes necessary to understand Jekyll.

+

+
+

+  
Warnings help you not blow things up

+  
Be aware of these messages if you wish to avoid certain death.

+

+
+If you come across anything along the way that we haven’t covered, or if you know of a tip yourself you think others would find handy, please [file an issue](https://github.com/mojombo/jekyll/issues/new) and we’ll see about including it in this guide.
diff --git a/site/_posts/2012-07-01-installation.md b/site/_posts/2012-07-01-installation.md
new file mode 100644
index 00000000000..190645fbfdd
--- /dev/null
+++ b/site/_posts/2012-07-01-installation.md
@@ -0,0 +1,43 @@
+---
+layout: docs
+title: Installation
+prev_section: home
+next_section: usage
+---
+
+Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain in the ass, you should [file an issue](https://github.com/mojombo/jekyll/issues/new) (or submit a pull request) about what might be a better way to do things.
+
+### Requirements
+
+Installing Jekyll is easy and straight-forward, but there’s a few requirements you’ll need to make sure your system has before you start.
+
+- [Ruby](http://www.ruby-lang.org/en/downloads/)
+- [RubyGems](http://rubygems.org/pages/download)
+- Linux, Unix, or Mac OS X
+
+

+  
Running Jekyll on Windows

+  
It is possible to get Jekyll running on Windows however the official documentation does not support installation on Windows platforms.

+

+
+## Install with RubyGems
+
+The best way to install Jekyll is via
+[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt, simply run the following command to install Jekyll:
+
+{% highlight bash %}
+gem install jekyll
+{% endhighlight %}
+
+All Jekyll’s gem dependancies are automatically installed by the above command, so you won’t have to worry about them at all. If you have problems installing Jekyll, check out the [troubleshooting](../troubleshooting) page or [report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll community can improve the experience for everyone.
+
+## Optional 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. These extras include syntax highlighting of code snippets using [Pygments](http://pygments.org/), LaTeX support, and the use of alternative content rendering engines. Check out [the extras page](../extras) for more information.
+
+

+  
ProTip™: Enable Syntax Highlighting

+  
If you’re the kind of person who is using Jekyll, then chances are you’ll definitely want to enable syntax highlighting using Pygments. You should really check out how to do that before you go any further.

+

+
+Now that you’ve got everything installed, let’s get to work!
diff --git a/site/_posts/2012-07-01-migrations.md b/site/_posts/2012-07-01-migrations.md
new file mode 100644
index 00000000000..3360fe4b1f0
--- /dev/null
+++ b/site/_posts/2012-07-01-migrations.md
@@ -0,0 +1,180 @@
+---
+layout: docs
+title: Blog migrations
+prev_section: variables
+next_section: templates
+---
+
+If you’re switching to Jekyll from another blogging system, Jekyll’s migrators can help you with the move. Most methods listed on this page require read access to the database to generate posts from your old system. Each method generates `.markdown` posts in the `_posts` directory based on the entries in the database.
+
+## Preparing for migrations
+
+The migrators are [built-in to the Jekyll gem](https://github.com/mojombo/jekyll/tree/master/lib/jekyll/migrators), and require a few things to be set up in your project directory before they are run. This should all be done from the root folder of your Jekyll project.
+
+{% highlight bash %}
+$ mkdir _import
+$ gem install sequel mysqlplus
+{% endhighlight %}
+
+You should now be all set to run the migrators below.
+
+

+  
Note: Always double-check migrated content

+  
Import scripts may not distinguish between published or private posts, so you should always check that the content Jekyll generates for you appears as you intended.

+

+
+## WordPress
+
+### Wordpress export files
+
+If hpricot is not already installed, you will need to run `gem install hpricot`. Next, export your blog using the Wordpress export utility. Assuming that exported file is saved as `wordpress.xml`, here is the command you need to run:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
+    Jekyll::WordpressDotCom.process("wordpress.xml")'
+{% endhighlight %}
+
+

+  
ProTip™: Wordpress.com Export Tool

+  
If you are migrating from a Wordpress.com account, you can access the export tool at the following URL: `https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php`.

+

+
+### Using Wordpress MySQL server connection
+
+If you want to import using a direct connection to the Wordpress MySQL server, here's how:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
+    Jekyll::WordPress.process("database", "user", "pass")'
+{% endhighlight %}
+
+If you are using Webfaction and have to set an [SSH tunnel](http://docs.webfaction.com/user-guide/databases.html?highlight=mysql#starting-an-ssh-tunnel-with-ssh), make sure to make the hostname (`127.0.0.1`) explicit, otherwise MySQL may block your access based on localhost and `127.0.0.1` not being equivalent in its authentication system:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
+    Jekyll::WordPress.process("database", "user", "pass", "127.0.0.1")'
+{% endhighlight %}
+
+### Further Wordpress migration alternatives
+
+While the above methods work, they do not import much of the metadata that is usually stored in Wordpress posts and pages. If you need to export things like pages, tags, custom fields, image attachments and so on, the following resources might be useful to you:
+
+- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in Python for migrating one or more Wordpress blogs into Jekyll (Markdown) format while keeping as much metadata as possible. Exitwp also downloads attachments and pages.
+- [A great article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a step-by-step guide for migrating a Wordpress blog to Jekyll while keeping most of the structure and metadata.
+- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable windows application for creating Markdown posts from your Wordpress XML file.
+
+## Drupal
+
+If you’re migrating from [Drupal](), there is [a migrator](https://github.com/mojombo/jekyll/blob/master/lib/jekyll/migrators/drupal.rb) for you too:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
+    Jekyll::Drupal.process("database", "user", "pass")'
+{% endhighlight %}
+
+

+  
Warning: Drupal Version Compatibility

+  
This migrator was written for Drupal 6.1 and may not work as expected on future versions of Drupal. Please update it and send us a pull request if necessary.

+

+
+## Movable Type
+
+To import posts from Movable Type:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/mt";
+    Jekyll::MT.process("database", "user", "pass")'
+{% endhighlight %}
+
+## Typo
+
+To import posts from Typo:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/typo";
+    Jekyll::Typo.process("database", "user", "pass")'
+{% endhighlight %}
+
+This code also has only been tested with Typo version 4+.
+
+## TextPattern
+
+To import posts from TextPattern:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/textpattern";
+    Jekyll::TextPattern.process("database_name", "username", "password", "hostname")'
+{% endhighlight %}
+
+You will need to run the above from the parent directory of your `_import` folder. For example, if `_import` is located in `/path/source/_import`, you will need to run this code from `/path/source`. The hostname defaults to `localhost`, all other variables are required. You may need to adjust the code used to filter entries. Left alone, it will attempt to pull all entries that are live or sticky.
+
+## Mephisto
+
+To import posts from Mephisto:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
+    Jekyll::Mephisto.process("database", "user", "password")'
+{% endhighlight %}
+
+If your data is in Postgres, you should do this instead:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
+    Jekyll::Mephisto.postgres({:database => "database", :username=>"username", :password =>"password"})'
+{% endhighlight %}
+
+## Blogger (Blogspot)
+
+To import posts from Blogger, see [this post about migrating from Blogger to Jekyll](http://coolaj86.info/articles/migrate-from-blogger-to-jekyll.html). If that doesn’t work for you, you might want to try some of the following alternatives:
+
+- [@kennym](https://github.com/kennym) created a [little migration script](https://gist.github.com/1115810), because the solutions in the previous article didn't work out for him.
+- [@ngauthier](https://github.com/ngauthier) created [another importer](https://gist.github.com/1506614) that imports comments, and does so via blogger’s archive instead of the RSS feed.
+- [@juniorz](https://github.com/juniorz) created [yet another importer](https://gist.github.com/1564581) that works for [Octopress](http://octopress.org). It is like [@ngauthier’s version](https://gist.github.com/1506614) but separates drafts from posts, as well as importing tags and permalinks.
+
+## Posterous
+
+To import posts from your primary Posterous blog:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
+    Jekyll::Posterous.process("my_email", "my_pass")'
+{% endhighlight %}
+
+For any other Posterous blog on your account, you will need to specify the `blog_id` for the blog:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
+    Jekyll::Posterous.process("my_email", "my_pass", "blog_id")'
+{% endhighlight %}
+
+There is also an [alternative Posterous migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb) that maintains permalinks and attempts to import images too.
+
+## Tumblr
+
+To import posts from Tumblr:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
+    Jekyll::Tumblr.process("http://www.your_blog_url.com", true)'
+{% endhighlight %}
+
+There is also [a modified Tumblr migrator](https://github.com/stephenmcd/jekyll/blob/master/lib/jekyll/migrators/tumblr.rb) that exports posts as Markdown and preserves post tags.
+
+The migrator above requires the `json` gem and Python's `html2text` to be installed as follows:
+
+{% highlight bash %}
+$ gem install json
+$ pip install html2text
+{% endhighlight %}
+
+Once installed, simply use the format argument:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
+    Jekyll::Tumblr.process("http://www.your_blog_url.com", format="md")'
+{% endhighlight %}
+
+## Other Systems
+
+If you have a system that there isn’t currently a migrator for, you should consider writing one and sending us a pull request.
\ No newline at end of file
diff --git a/site/_posts/2012-07-01-pages.md b/site/_posts/2012-07-01-pages.md
new file mode 100644
index 00000000000..c53e06c2869
--- /dev/null
+++ b/site/_posts/2012-07-01-pages.md
@@ -0,0 +1,62 @@
+---
+layout: docs
+title: Creating pages
+prev_section: posts
+next_section: variables
+---
+
+As well as [writing posts](../posts), the other thing you may want to do with your Jekyll site is create static pages. This is pretty simple to do, simply by taking advantage of the way Jekyll copies files and directories.
+
+## Homepage
+
+Just about every web server configuration you’ll come across will look for a HTML file called `index.html` (by convention) in the site root folder and display that as the homepage. Unless the web server you’re using is configured to look for some different filename as the default, this file will turn into the homepage of your Jekyll-generated site.
+
+

+  
ProTip™: Use layouts on your homepage

+  
Any HTML file on your site can make use of layouts and includes, even the homepage. It’s usually a good idea to extract everything that is the same across all your pages into an included file in a layout.

+

+
+## Where additional pages live
+
+Where you put HTML files for pages depends on how you want the pages to work, since there are two main ways of creating pages:
+
+- By placing named HTML files for each page in the site root folder.
+- Create a folder in the site root for each page, and placing an index.html file in each page folder.
+
+Both methods work fine (and can be used in conduction with each other), with the only real difference being the resulting URLs each page has.
+
+### Named HTML files
+
+The simplest way of adding a page is just to add a HTML file in the root directory with a suitable name for the page you want to create. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like.
+
+{% highlight bash %}
+.
+|-- _config.yml
+|-- _includes
+|-- _layouts
+|-- _posts
+|-- _site
+|-- about.html    #=> http://yoursite.com/about.html
+|-- index.html    #=> http://yoursite.com/
+└── contact.html  #=> http://yoursite.com/contact.html
+{% endhighlight %}
+
+### Named folders containing index HTML files
+
+There is nothing wrong with the above method, however some people like to keep their URLs free from things like filename extensions. To achieve clean URLs for pages using Jekyll, you simply need to create a folder for each top-level page you want, and then place an `index.html` file in each page’s folder. This way the page URL ends up being the folder name, and the web server will serve up the respective `index.html` file. An example of what this structure would look like is as follows:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes
+├── _layouts
+├── _posts
+├── _site
+├── about
+|   └── index.html  #=> http://yoursite.com/about/
+├── contact
+|   └── index.html  #=> http://yoursite.com/contact/
+└── index.html      #=> http://yoursite.com/
+{% endhighlight %}
+
+This approach may not suit everyone, but for people who like clear URLs it’s simple and it works. In the end the decision is yours!
diff --git a/site/_posts/2012-07-01-pagination.md b/site/_posts/2012-07-01-pagination.md
new file mode 100644
index 00000000000..a82d0fdb1b8
--- /dev/null
+++ b/site/_posts/2012-07-01-pagination.md
@@ -0,0 +1,116 @@
+---
+layout: docs
+title: Pagination
+prev_section: permalinks
+next_section: plugins
+---
+
+With many websites—especially blogs—it’s very common to break the main listing of posts up into smaller lists and display them over multiple pages. Jekyll has pagination built-in, so you can automatically generate the appropriate files and folders you need for paginated post listings.
+
+

+  
Pagination only works within HTML files

+  
Pagination does not work with Markdown or Textile files in your Jekyll site. It will only work when used within HTML files. Since you’ll likely be using this for the list of posts, this probably won’t be an issue.

+

+
+## Enable pagination
+
+The first thing you need to do to enable pagination for your blog is add a line to the `_config.yml` Jekyll configuration file that specifies how many items should be displayed per page. Here is what the line should look like:
+
+{% highlight yaml %}
+paginate: 5
+{% endhighlight %}
+
+The number should be the maximum number of posts you’d like to be displayed per-page in the generated site.
+
+## Render the paginated posts
+
+The next thing you need to do is to actually display your posts in a list using the `paginator` variable that will now be available to you. You’ll probably want to do this in one of the main pages of your site. Here’s one example of a simple way of rendering paginated posts in a HTML file:
+
+{% highlight html %}
+---
+layout: default
+title: My Blog
+---
+
+
+{{ "{% for post in paginator.posts " }}%}
+  
{{ "{{ post.title " }}}}

+  

+    {{ "{{post.date" }}}}
+  

+  

+    {{ "{{ post.content " }}}}
+  

+{{ "{% endfor " }}%}
+
+
+
+{% endhighlight %}
+
+

+  
Beware the page one edge-case

+  
Jekyll does not generate a ‘page1’ folder, so the above code will not work when a /page1 link is produced. See below for a way to handle this if it’s a problem for you.

+

+
+The following HTML snippet should handle page one, and render a list of each page with links to all but the current page.
+
+{% highlight html %}
+
+{% endhighlight %}
diff --git a/site/_posts/2012-07-01-permalinks.md b/site/_posts/2012-07-01-permalinks.md
new file mode 100644
index 00000000000..9bee0d726ea
--- /dev/null
+++ b/site/_posts/2012-07-01-permalinks.md
@@ -0,0 +1,163 @@
+---
+layout: docs
+title: Permalinks
+prev_section: templates
+next_section: pagination
+---
+
+Jekyll supports a flexible way to build your site’s URLs. You can
+specify the permalinks for your site through the [Configuration](../configuration) or on the [YAML Front Matter](../frontmatter) for each post. You’re free to choose one of the built-in styles to create your links or craft your own. The default style is always `date`.
+
+## Template variables
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
VariableDescription

+        
year

+      		
+        
Year from the post’s filename

+      

+        
month

+      		
+        
Month from the post’s filename

+      

+        
day

+      		
+        
Day from the post’s filename

+      

+        
title

+      		
+        
Title from the post’s filename

+      

+        
categories

+      		
+        
The specified categories for this post. Jekyll automatically parses out double slashes in the URLs, so if no categories are present, it basically ignores this.

+      

+        
i_month

+      		
+        
 Month from the post’s filename without leading zeros.

+      

+        
i_day

+      		
+        
Day from the post’s filename without leading zeros.

+      

+
+## Built-in permalink styles
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
Permalink StyleURL Template

+        
date

+      		
+        
/:categories/:year/:month/:day/:title.html

+      

+        
pretty

+      		
+        
/:categories/:year/:month/:day/:title/

+      

+        
none

+      		
+        
/:categories/:title.html

+      

+
+## Permalink style examples
+
+Given a post named: `/2009-04-29-slap-chop.textile`
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
Permalink SettingResulting Permalink URL

+        
None specified, or permalink: date

+      		
+        
/2009/04/29/slap-chop.html

+      

+        
permalink: pretty

+      		
+        
/2009/04/29/slap-chop/index.html

+      

+        
permalink: /:month-:day-:year/:title.html

+      		
+        
/04-29-2009/slap-chop.html

+      

+        
permalink: /blog/:year/:month/:day/:title

+      		
+        
/blog/2009/04/29/slap-chop/index.html

+      

+
diff --git a/site/_posts/2012-07-01-plugins.md b/site/_posts/2012-07-01-plugins.md
new file mode 100644
index 00000000000..6543e621c8e
--- /dev/null
+++ b/site/_posts/2012-07-01-plugins.md
@@ -0,0 +1,384 @@
+---
+layout: docs
+title: Plugins
+prev_section: assets
+next_section: extras
+---
+
+Jekyll has a plugin system with hooks that allow you to create custom generated
+content specific to your site. You can run custom code for your site
+without having to modify the Jekyll source itself.
+
+

+  
Plugins on GitHub Pages

+  
GitHub Pages are powered by Jekyll, however all Pages sites are generated using the --safe option to disable custom plugins for security reasons. Unfortunately, this means your plugins won’t work if you’re deploying to GitHub Pages.

+

+
+## Installing a plugin
+
+In your site source root, make a `_plugins` directory. Place your plugins
+here. Any file ending in `*.rb` inside this directory will be required
+when Jekyll generates your site.
+
+In general, plugins you make will fall into one of three categories:
+
+1. Generators
+2. Converters
+3. Tags
+
+## Generators
+
+You can create a generator when you need Jekyll to create additional
+content based on your own rules. For example, a generator might look
+like this:
+
+{% highlight ruby %}
+module Jekyll
+
+  class CategoryPage < Page
+    def initialize(site, base, dir, category)
+      @site = site
+      @base = base
+      @dir = dir
+      @name = 'index.html'
+
+      self.process(@name)
+      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
+      self.data['category'] = category
+
+      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
+      self.data['title'] = "#{category_title_prefix}#{category}"
+    end
+  end
+
+  class CategoryPageGenerator < Generator
+    safe true
+
+    def generate(site)
+      if site.layouts.key? 'category_index'
+        dir = site.config['category_dir'] || 'categories'
+        site.categories.keys.each do |category|
+          site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
+        end
+      end
+    end
+  end
+
+end
+{% endhighlight %}
+
+In this example, our generator will create a series of files under the
+`categories` directory for each category, listing the posts in each
+category using the `category_index.html` layout.
+
+Generators are only required to implement one method:
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
MethodDescription

+        
generate

+      		
+        
String output of the content being generated.

+      

+
+## Converters
+
+If you have a new markup language you’d like to include in your site,
+you can include it by implementing your own converter. Both the markdown
+and textile markup languages are implemented using this method.
+
+

+  
Remember your YAML front-matter

+  
Jekyll will only convert files that have a YAML header at
+the top, even for converters you add using a plugin. If there is no YAML header, Jekyll will ignore the file and not send it through the converter.

+

+
+Below is a converter that will take all posts ending in .upcase and
+process them using the UpcaseConverter:
+
+{% highlight ruby %}
+module Jekyll
+  class UpcaseConverter < Converter
+    safe true
+    priority :low
+
+    def matches(ext)
+      ext =~ /upcase/i
+    end
+
+    def output_ext(ext)
+      ".html"
+    end
+
+    def convert(content)
+      content.upcase
+    end
+  end
+end
+{% endhighlight %}
+
+Converters should implement at a minimum 3 methods:
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
MethodDescription

+        
matches

+      		
+        
Called to determine whether the specific converter will
+run on the page.

+      

+        
output_ext

+      		
+        
The extension of the outputted file, usually this will be .html

+      

+        
convert

+      		
+        
Logic to do the content conversion

+      

+
+In our example, UpcaseConverter-matches checks if our filename extension is `.upcase`, and will render using the converter if it is. It will call UpcaseConverter-convert to process the content - in our simple converter we’re simply capitalizing the entire content string. Finally, when it saves the page, it will do so with the `.html` extension.
+
+## Tags
+
+If you’d like to include custom liquid tags in your site, you can do so
+by hooking into the tagging system. Built-in examples added by Jekyll
+include the `{{"{% highlight "}}%}` and `{{"{% include "}}%}` tags. Below is an example custom liquid tag that will output the time the page was rendered:
+
+{% highlight ruby %}
+module Jekyll
+  class RenderTimeTag < Liquid::Tag
+
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+
+    def render(context)
+      "#{@text} #{Time.now}"
+    end
+  end
+end
+
+Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
+{% endhighlight %}
+
+At a minimum, liquid tags must implement:
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
MethodDescription

+        
render

+      		
+        
Outputs the content of the tag.

+      

+
+You must also register the custom tag with the Liquid template engine as follows:
+
+{% highlight ruby %}
+Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
+{% endhighlight %}
+
+In the example above, we can place the following tag anywhere in one of our pages:
+
+{% highlight ruby %}
+
{{"{% render_time page rendered at: "}}%}

+{% endhighlight %}
+
+And we would get something like this on the page:
+
+{% highlight html %}
+
page rendered at: Tue June 22 23:38:47 –0500 2010

+{% endhighlight %}
+
+### Liquid filters
+
+You can add your own filters to the Liquid template system much like you can add tags above. Filters are simply modules that export their methods to liquid. All methods will have to take at least one parameter which represents the input of the filter. The return value will be the output of the filter.
+
+{% highlight ruby %}
+module Jekyll
+  module AssetFilter
+    def asset_url(input)
+      "http://www.example.com/#{input}?#{Time.now.to_i}"
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::AssetFilter)
+{% endhighlight %}
+
+

+  
ProTip™: Access the site object using Liquid

+  
Jekyll lets you access the site object through the context.registers feature of liquid. For example, you can access the global configuration file _config.yml using context.registers.config.

+

+
+### Flags
+
+There are two flags to be aware of when writing a plugin:
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
FlagDescription

+        
safe

+      		
+        
A boolean flag that allows a plugin to be safely included in
+Jekyll core for exclusion from use with GitHub Pages. In general, set
+this to true.

+      

+        
priortiy

+      		
+        
This flag determines what order the plugin is loaded in. Valid
+values are: :lowest, :low, :normal, :high, and :highest.

+      

+
+To use one of the example plugins above as an illustration, here is how you’d specify these two flags:
+
+{% highlight ruby %}
+module Jekyll
+  class UpcaseConverter < Converter
+    safe true
+    priority :low
+    ...
+  end
+end
+{% endhighlight %}
+
+
+## Available Plugins
+
+There are a few useful, prebuilt plugins at the following locations:
+
+- [Truncate HTML while preserving markup structure](https://github.com/MattHall/truncatehtml) by [Matt Hall](http://codebeef.com)
+- [Generic Blog Plugins by Jose Diaz-Gonzalez](https://github.com/josegonzalez/josediazgonzalez.com/tree/master/_plugins): Contains plugins for tags, categories, archives, as well as a few liquid extensions
+- [Domain Name Filter by Lawrence Woodman](https://github.com/LawrenceWoodman/domain_name-liquid_filter): Filters the input text so that just the domain name is left
+- [Jekyll Plugins by Recursive Design](http://recursive-design.com/projects/jekyll-plugins/): Plugin to generate Project pages from github readmes, a Category page plugin, and a Sitemap generator
+- [Tag Cloud Plugin from a Jekyll walk-through](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/): Plugin to generate a Tag Cloud
+- [Pygments Cache Path by Raimonds Simanovskis](https://github.com/rsim/blog.rayapps.com/blob/master/_plugins/pygments_cache_patch.rb): Plugin to cache syntax-highlighted code from Pygments
+- [Delicious Plugin by Christian Hellsten](https://github.com/christianhellsten/jekyll-plugins): Fetches and renders bookmarks from delicious.com.
+- [Ultraviolet plugin by Steve Alex](https://gist.github.com/480380): Jekyll Plugin for Ultraviolet
+- [HAML plugin by Sam Z](https://gist.github.com/517556): HAML plugin for jekyll
+- [ArchiveGenerator by Ilkka Laukkanen](https://gist.github.com/707909): Uses [this archive page](https://gist.github.com/707020) to generate archives
+- [Tag Cloud Plugin by Ilkka Laukkanen](https://gist.github.com/710577): Jekyll tag cloud / tag pages plugin
+- [HAML/SASS Converter by Adam Pearson](https://gist.github.com/481456): Simple haml-sass conversion for jekyll. [Fork](https://gist.github.com/528642) by Sam X
+- [SASS scss Converter by Mark Wolfe](https://gist.github.com/960150): Jekyll Converter which uses the new css compatible syntax, based on the one written by Sam X.
+- [GIT Tag by Alexandre Girard](https://gist.github.com/730347): Jekyll plugin to add Git activity inside a list
+- [Draft/Publish Plugin by Michael Ivey](https://gist.github.com/49630)
+- [Less.js generator by Andy Fowler](https://gist.github.com/642739): Jekyll plugin to render less.js files during generation.
+- [Less Converter by Jason Graham](https://gist.github.com/639920): A Jekyll plugin to convert a .less file to .css
+- [Less Converter by Josh Brown](https://gist.github.com/760265)
+
+- [MathJax Liquid Tags by Jessy Cowan-Sharp](https://gist.github.com/834610): A simple liquid tag for Jekyll that converts and into inline math, and and into block equations, by replacing with the appropriate MathJax script tags.
+- [Non-JS Gist Tag by Brandon Tilley](https://gist.github.com/1027674) A Liquid tag for Jekyll sites that allows embedding Gists and showing code for non-JavaScript enabled browsers and readers.
+- [Growl Notification Generator by Tate Johnson](https://gist.github.com/490101)
+- [Growl Notification Hook by Tate Johnson](https://gist.github.com/525267): Better alternative to the above, but requires his “hook” fork.
+- [Version Reporter by Blake Smith](https://gist.github.com/449491)
+- [Upcase Converter by Blake Smith](https://gist.github.com/449463)
+- [Render Time Tag by Blake Smith](https://gist.github.com/449509)
+- [Summarize Filter by Mathieu Arnold](https://gist.github.com/731597)
+- [Status.net/OStatus Tag by phaer](https://gist.github.com/912466)
+- [CoffeeScript converter by phaer](https://gist.github.com/959938): Put this file in `plugins` and write a YAML header to your .coffee files. See [http://coffeescript.org](http://coffeescript.org) for more info
+- [Raw Tag by phaer.](https://gist.github.com/1020852): Keeps liquid from parsing text betweeen `{{ "{% raw " }}%}` and `{{ "{% endraw " }}%}`
+- [URL encoding by James An](https://gist.github.com/919275)
+- [Sitemap.xml Generator by Michael Levin](http://www.kinnetica.com/projects/jekyll-sitemap-generator/)
+- [Markdown references by Olov Lassus](https://gist.github.com/961336): Keep all your markdown reference-style link definitions in one file (_references.md)
+- [Full-text search by Pascal Widdershoven](https://github.com/PascalW/jekyll_indextank): Add full-text search to your Jekyll site with this plugin and a bit of JavaScript.
+- [Stylus Converter](https://gist.github.com/988201) Convert .styl to .css.
+- [Embed.ly client by Robert Böhnke](https://github.com/robb/jekyll-embedly-client) Autogenerate embeds from URLs using oEmbed.
+- [Logarithmic Tag Cloud](https://gist.github.com/2290195): Flexible. Logarithmic distribution. Usage eg: `{{ "{% tag_cloud font-size: 50 - 150%, threshold: 2 " }}%}`. Documentation inline.
+- [Related Posts by Lawrence Woodman](https://github.com/LawrenceWoodman/related_posts-jekyll_plugin): Overrides `site.related_posts` to use categories to assess relationship
+- [AliasGenerator by Thomas Mango](https://github.com/tsmango/jekyll_alias_generator): Generates redirect pages for posts when an alias configuration is specified in the YAML Front Matter.
+- [FlickrSetTag by Thomas Mango](https://github.com/tsmango/jekyll_flickr_set_tag): Generates image galleries from Flickr sets.
+- [Projectlist by Frederic Hemberger](https://github.com/fhemberger/jekyll-projectlist): Loads all files from a directory and renders the entries into a single page, instead of creating separate posts.
+- [Tiered Archives by Eli Naeher](https://gist.github.com/88cda643aa7e3b0ca1e5): creates a tiered template variable that allows you to create archives grouped by year and month.
+- [Jammit generator by Vladimir Andrijevik](https://gist.github.com/1224971): enables use of [Jammit](http://documentcloud.github.com/jammit/) for JavaScript and CSS packaging.
+- [oEmbed Tag by Tammo van Lessen](https://gist.github.com/1455726): enables easy content embedding (e.g. from YouTube, Flickr, Slideshare) via oEmbed.
+- [Company website and blog plugins](https://github.com/flatterline/jekyll-plugins) by Flatterline, a [Ruby on Rails development company](http://flatterline.com/): portfolio/project page generator, team/individual page generator, author bio liquid template tag for use on posts and a few other smaller plugins.
+- [Transform Layouts](https://gist.github.com/1472645) Monkey patching allowing HAML layouts (you need a HAML Converter plugin for this to work)
+- [ReStructuredText converter](https://github.com/xdissent/jekyll-rst): Converts ReST documents to HTML with Pygments syntax highlighting.
+- [Tweet Tag by Scott W. Bradley](https://github.com/scottwb/jekyll-tweet-tag): Liquid tag for [Embedded Tweets](https://dev.twitter.com/docs/embedded-tweets) using Twitter’s shortcodes
+- [jekyll-localization](https://github.com/blackwinter/jekyll-localization): Jekyll plugin that adds localization features to the rendering engine.
+- [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.
+- [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.
+- [jsonball](https://gist.github.com/1895282): reads json files and produces maps for use in jekylled files
+- [redcarpet2](https://github.com/nono/Jekyll-plugins): use Redcarpet2 for rendering markdown
+- [bibjekyll](https://github.com/pablooliveira/bibjekyll): render BibTeX-formatted bibliographies/citations included in posts/pages using bibtex2html
+- [jekyll-citation](https://github.com/archome/jekyll-citation): render BibTeX-formatted bibliographies/citations included in posts/pages (pure Ruby)
+- [jekyll-scholar](https://github.com/inukshuk/jekyll-scholar): Jekyll extensions for the blogging scholar
+- [jekyll-asset_bundler](https://github.com/moshen/jekyll-asset_bundler): bundles and minifies JavaScript and CSS
+- [Jekyll Dribbble Set Tag](https://github.com/ericdfields/Jekyll-Dribbble-Set-Tag): builds Dribbble image galleries from any user
+- [debbugs](https://gist.github.com/2218470): allows posting links to Debian BTS easily
+- [refheap_tag](https://github.com/aburdette/refheap_tag): Liquid tag that allows embedding pastes from [refheap](https://refheap.com)
+- [i18n_filter](https://github.com/gacha/gacha.id.lv/blob/master/_plugins/i18n_filter.rb): Liquid filter to use I18n localization.
+- [singlepage-jekyll](https://github.com/JCB-K/singlepage-jekyll) by [JCB-K](https://github.com/JCB-K): turns Jekyll into a dynamic one-page website.
+- [flickr](http://jonasforsberg.se/2012/04/15/flickr-plugin-for-jekyll/): Embed photos from flickr right into your posts.
+- [jekyll-devonly_tag](https://gist.github.com/2403522): A block tag for including markup only during development.
+- [Jekyll plugins by Aucor](https://github.com/aucor/jekyll-plugins): Plugins for eg. trimming unwanted newlines/whitespace and sorting pages by weight attribute.
+- [Only first paragraph](https://github.com/sebcioz/jekyll-only_first_p): Show only first paragrpaph of page/post.
+- [jekyll-pandoc-plugin](https://github.com/dsanson/jekyll-pandoc-plugin): use pandoc for rendering markdown.
+- [File compressor](https://gist.github.com/2758691) by [mytharcher](https://github.com/mytharcher): Compress HTML (\*.html) and JavaScript(\*.js) files when output.
+- [smilify](https://github.com/SaswatPadhi/jekyll_smilify) by [SaswatPadhi](https://github.com/SaswatPadhi): Convert text emoticons in your content to themeable smiley pics. [Demo](http://saswatpadhi.github.com/)
+- [excerpts](http://blog.darkrefraction.com/2012/jekyll-excerpt-plugin.html) by [drawoc](https://github.com/drawoc): provides a nice way to implement page excerpts.
+
+

+  
Jekyll Plugins Wanted

+  
If you have a Jekyll plugin that you would like to see added to this list, you should read the contributing page to find out how to make that happen.

+

diff --git a/site/_posts/2012-07-01-posts.md b/site/_posts/2012-07-01-posts.md
new file mode 100644
index 00000000000..2871213b33d
--- /dev/null
+++ b/site/_posts/2012-07-01-posts.md
@@ -0,0 +1,106 @@
+---
+layout: docs
+title: Writing posts
+prev_section: frontmatter
+next_section: pages
+---
+
+One of Jekyll’s best aspects is that it is “blog aware”. What does that mean, exactly? Well, simply put it means that blogging is baked into Jekyll’s functionality by default. For people who write articles and publish them online, this means that you can publish and maintain a blog simply by managing a folder full of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change for many.
+
+## The Posts Folder
+
+As detailed on the [directory structure](../structure) page, the `_posts` folder in any Jekyll site is where the files for all your articles will live. These files can be either [Markdown](http://daringfireball.net/projects/markdown/) or [Textile](http://textile.sitemonks.com/) formatted text files, and as long as they have [YAML front-matter](../frontmatter) defined, they will be converted from their source format into a HTML page that is part of your static site.
+
+### Creating Post Files
+
+To create a new post, all you need to do is create a new file in the `_posts` folder. The filename structure used for files in this folder is important—Jekyll requires the file to be named in the following format:
+
+{% highlight bash %}
+YEAR-MONTH-DAY-title.MARKUP
+{% endhighlight %}
+
+Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is an appropriate file extension for the format your post is written in. For example, the following are examples of excellent post filenames:
+
+{% highlight bash %}
+2011-12-31-new-years-eve-is-awesome.markdown
+2012-09-12-how-to-write-a-blog.textile
+{% endhighlight %}
+
+### Content Formats
+
+The first thing you need to put in any post is a section for [YAML front-matter](../frontmatter), but after that, it's simply a case of deciding which format you prefer to write in. Jekyll supports two popular content markup formats: [Markdown](http://daringfireball.net/projects/markdown/) or [Textile](http://textile.sitemonks.com/). These formats each have their own way of signifying different types of content within a post, so you should read up on how these formats work and decide which one suits your needs best.
+
+## Including images and resources
+
+For people who publish articles on a regular basis, it’s quite common to need to include things like images, links, downloads, and other resources along with their text-based content. While the ways to link to these resources differ between Markdown and Textile, the problem of working out where to store these files in your site is something everyone will face.
+
+Because of Jekyll’s flexibility, there are many solutions to how to do this. One common solution is to create a folder in the root of the project directory called something like `assets` or `downloads`, into which any images, downloads or other resources are placed. Then, from within any post, they can be linked to using the site’s root as the path for the asset to include. Again, this will depend on the way your site’s (sub)domain and path are configured, but here some examples (in Markdown) of how you could do this using the `{{ "{{ site.url " }}}}` variable in a post.
+
+Including an image asset in a post:
+
+{% highlight bash %}
+… which is shown in the screenshot below:
+![My helpful screenshot]({{ "{{ site.url " }}}}/assets/screenshot.jpg)
+{% endhighlight %}
+
+Linking to a PDF for readers to download:
+
+{% highlight bash %}
+… you can [get the PDF]({{ "{{ site.url " }}}}/assets/mydoc.pdf) directly.
+{% endhighlight %}
+
+

+  
ProTip™: Link using just the site root URL

+  
You can skip the {{ "{{ site.url " }}}} variable if you know your site will only ever be displayed at the root URL of your domain. In this case you can reference assets directly with just /path/file.jpg.

+

+
+## Displaying an index of posts
+
+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 for people. 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 it’s tags. Here’s a basic example of how to create an unordered list of links to posts for a Jekyll site:
+
+{% highlight html %}
+
+{% endhighlight %}
+
+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’re interested in these kinds of things.
+
+## Highlighting code snippets
+
+Jekyll also has built-in support for syntax highlighting of code snippets using [Pygments](../extras), and including a code snippet in any post is easy. Just use the dedicated Liquid tag as follows:
+
+{% highlight ruby %}
+{{ "{% highlight ruby"}} %}
+def show
+  @widget = Widget(params[:id])
+  respond_to do |format|
+    format.html # show.html.erb
+    format.json { render json: @widget }
+  end
+end
+{{ "{% endhighlight"}} %}
+{% endhighlight %}
+
+And the output will look like this:
+
+{% highlight ruby %}
+def show
+  @widget = Widget(params[:id])
+  respond_to do |format|
+    format.html # show.html.erb
+    format.json { render json: @widget }
+  end
+end
+{% endhighlight %}
+
+

+  
ProTip™: Show line numbers

+  
You can make code snippets include line-numbers easily, simply add the word linenos to the end of the opening highlight tag like this: {{ "{% highlight ruby linenos " }}%}.

+

+
+Those basics should be more than enough to get you started writing your first posts. When you’re ready to dig into what else is possible, you might be interested in doing things like [customizing post permalinks](../permalinks) or using [custom variables](../variables) in your posts and elsewhere on your site.
\ No newline at end of file
diff --git a/site/_posts/2012-07-01-resources.md b/site/_posts/2012-07-01-resources.md
new file mode 100644
index 00000000000..c14c584c285
--- /dev/null
+++ b/site/_posts/2012-07-01-resources.md
@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Resources
+prev_section: sites
+---
+
+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.
+
+### Jekyll tips & tricks, and examples
+
+- [A simple way to add draft posts](https://gist.github.com/2870636)
+
+  No plugins required.
+
+- [Tips for working with GitHub Pages Integration](https://gist.github.com/2890453)
+
+  Code example reuse, and keeping documentation up to date.
+
+- [Use Simple Form to integrate a simple contact
+  form](http://getsimpleform.com/)
+- [JekyllBootstrap.com](http://jekyllbootstrap.com)
+
+  Provides detailed explanations, examples, and helper-code to make
+  getting started with Jekyll easier.
+
+### Tutorials
+
+#### Integrating Jekyll with Git
+
+- [Blogging with Git, Emacs and Jekyll](http://metajack.im/2009/01/23/blogging-with-git-emacs-and-jekyll/)
+- [Using Git to maintain your blog](http://matedriven.com.ar/2009/04/28/using-git-to-maintain-your-blog.html) (step by step guide)
+
+#### Other hacks
+
+- [Integrating Twitter with Jekyll](http://www.justkez.com/integrating-twitter-with-jekyll/)
+  > “Having migrated Justkez.com to be based on Jekyll, I was pondering how I might include my recent twitterings on the front page of the site. In the Wordpress world, this would have been done via a plugin which may or may not have hung the loading of the page, might have employed caching, but would certainly have had some overheads. … Not in Jekyll.”
+- [‘My Jekyll Fork’, by Mike West](http://mikewest.org/2009/11/my-jekyll-fork)
+  > “Jekyll is a well-architected throwback to a time before Wordpress, when men were men, and HTML was static. I like the ideas it espouses, and have made a few improvements to it’s core. Here, I’ll point out some highlights of my fork in the hopes that they see usage beyond this site.”
+- [‘About this Website’, by Carter Allen](http://cartera.me/2010/08/12/about-this-website/)
+  > “Jekyll is everything that I ever wanted in a blogging engine. Really. It isn’t perfect, but what’s excellent about it is that if there’s something wrong, I know exactly how it works and how to fix it. It runs on the your machine only, and is essentially an added”build" step between you and the browser. I coded this entire site in TextMate using standard HTML5 and CSS3, and then at the end I added just a few little variables to the markup. Presto-chango, my site is built and I am at peace with the world.”
+- [Generating a Tag Cloud in Jekyll](http://www.justkez.com/generating-a-tag-cloud-in-jekyll/)
+
+  A guide to implementing a tag cloud and per-tag content pages using Jekyll.
+
+- [Jekyll Extensions -= Pain](http://rfelix.com/2010/01/19/jekyll-extensions-minus-equal-pain/)
+
+  A way to [extend Jekyll](http://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](http://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reutilized and shared.
+
+- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)
diff --git a/site/_posts/2012-07-01-structure.md b/site/_posts/2012-07-01-structure.md
new file mode 100644
index 00000000000..78212f037d7
--- /dev/null
+++ b/site/_posts/2012-07-01-structure.md
@@ -0,0 +1,95 @@
+---
+layout: docs
+title: Directory structure
+prev_section: usage
+next_section: configuration
+---
+
+Jekyll at its core is a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout and more. This is all done through strictly editing files, and the web interface is the final product.
+
+A basic Jekyll site usually looks something like this:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes
+|   ├── footer.html
+|   └── header.html
+├── _layouts
+|   ├── default.html
+|   └── post.html
+├── _posts
+|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
+|   └── 2009-04-26-barcamp-boston-4-roundup.textile
+├── _site
+└── index.html
+{% endhighlight %}
+
+An overview of what each of these does:
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
File / DirectoryDescription

+        
_config.yml

+      		
+        
Stores configuration data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to remember them.

+      

+        
_includes

+      		
+        
These are the partials that can be mixed and matched by your _layouts and _posts to facilitate reuse.  The liquid tag {{ "{% include file.ext " }}%} can be used to include the partial in _includes/file.ext.

+      

+        
_layouts

+      		
+        
These are the templates which posts are inserted into. Layouts are chosen on a post-by-post basis in the YAML front matter, which is described in the next section. The liquid tag {{ "{{ content " }}}} is used to inject data onto the page.

+      

+        
_posts

+      		
+        
Your dynamic content, so to speak. The format of these files is important, as named as YEAR-MONTH-DAY-title.MARKUP. The permalinks can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.

+      

+        
_site

+      		
+        
This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your .gitignore file.

+      

+        
index.html and other HTML, Markdown, Textile files

+      		
+        
Provided that the file has a YAML Front Matter section, it will be transformed by Jekyll. The same will happen for any .html, .markdown, .md, or .textile file in your site's root directory or directories not listed above.

+      

+        
Other Files/Folders

+      		
+        
Every other directory and file except for those listed above—such as css and images folders, favicon.ico files, and so forth—will be transferred over verbatim to the generated site. There's plenty of sites already using Jekyll if you're curious as to how they're laid out.

+      

diff --git a/site/_posts/2012-07-01-templates.md b/site/_posts/2012-07-01-templates.md
new file mode 100644
index 00000000000..edd76a715f2
--- /dev/null
+++ b/site/_posts/2012-07-01-templates.md
@@ -0,0 +1,217 @@
+---
+layout: docs
+title: Templates
+prev_section: migrations
+next_section: permalinks
+---
+
+Jekyll uses the [Liquid](http://www.liquidmarkup.org/) 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 common tasks easier.
+
+## Filters
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
DescriptionFilter and Output

+        
Date to XML Schema

+        
Convert a Date into XML Schema format.

+      		
+        

+         {{ "{{ site.time | date_to_xmlschema " }}}}
+        

+        

+          2008-11-17T13:07:54-08:00
+        

+      

+        
Date to String

+        
Convert a date to short format.

+      		
+        

+         {{ "{{ site.time | date_to_string " }}}}
+        

+        

+          17 Nov 2008
+        

+      

+        
Date to Long String

+        
Format a date to long format.

+      		
+        

+         {{ "{{ site.time | date_to_long_string " }}}}
+        

+        

+          17 November 2008
+        

+      

+        
XML Escape

+        
Escape some text for use in XML.

+      		
+        

+         {{ "{{ page.content | xml_escape " }}}}
+        

+      

+        
CGI Escape

+        
CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.

+      		
+        

+         {{ "{{ “foo,bar;baz?” | cgi_escape " }}}}
+        

+        

+          foo%2Cbar%3Bbaz%3F
+        

+      

+        
Number of Words

+        
Count the number of words in some text.

+      		
+        

+         {{ "{{ page.content | number_of_words " }}}}
+        

+        

+          1337
+        

+      

+        
Array to Sentence

+        
Convert an array into a sentence. Useful for listing tags.

+      		
+        

+         {{ "{{ page.tags | array_to_sentence_string " }}}}
+        

+        

+          foo, bar, and baz
+        

+      

+        
Textilize

+        
Convert a Textile-formatted string into HTML, formatted via RedCloth

+      		
+        

+         {{ "{{ page.excerpt | textilize " }}}}
+        

+      

+        
Markdownify

+        
Convert a Markdown-formatted string into HTML.

+      		
+        

+         {{ "{{ page.excerpt | markdownify " }}}}
+        

+      

+
+## Tags
+
+### Includes (Partials)
+
+If you have small page fragments that you wish to include in multiple
+places on your site, you can use the `include` tag.
+
+{% highlight ruby %}
+{{ "{% include sig.textile " }}%}
+{% endhighlight %}
+
+Jekyll expects all include files to be placed in an `_includes`
+directory at the root of your source dir. So this will embed the
+contents of `/path/to/your/site/_includes/sig.textile` into the calling
+file.
+
+### Code snippet highlighting
+
+Jekyll has built in support for syntax highlighting of [over 100
+languages](http://pygments.org/languages/) thanks to
+[Pygments](http://pygments.org/). In order to take advantage of this
+you’ll need to have Pygments installed, and the `pygmentize` binary must
+be in your `$PATH`. When you run Jekyll, make sure you run it with
+[Pygments enabled](../extras).
+
+To render a code block with syntax highlighting, surround your code as follows:
+
+{% highlight ruby %}
+{{ "{% highlight ruby " }}%}
+def foo
+  puts 'foo'
+end
+{{ "{% endhighlight " }}%}
+{% endhighlight %}
+
+The argument to the `highlight` tag (`ruby` in the example above) is the language identifier. To find the appropriate identifier to use for the language you want to highlight, look for the “short name” on the [Lexers page](http://pygments.org/docs/lexers/).
+
+#### Line numbers
+
+There is a second argument to `highlight` called `linenos` that is
+optional. Including the `linenos` argument will force the highlighted
+code to include line numbers. For instance, the following code block
+would include line numbers next to each line:
+
+{% highlight ruby %}
+{{ "{% highlight ruby linenos " }}%}
+def foo
+  puts 'foo'
+end
+{{ "{% endhighlight " }}%}
+{% endhighlight %}
+
+#### Stylesheets for syntax highlighting
+
+In order for the highlighting to show up, you’ll need to include a
+highlighting stylesheet. For an example stylesheet you can look at
+[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css).
+These are the same styles as used by GitHub and you are free to use them
+for your own site. If you use linenos, you might want to include an
+additional CSS class definition for the `.lineno` class in `syntax.css` to
+distinguish the line numbers from the highlighted code.
+
+### Post URL
+
+If you would like to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify.
+
+{% highlight bash %}
+{{ "{% post_url 2010-07-21-name-of-post " }}%}
+{% endhighlight %}
+
+There is no need to include the file extension when using the `post_url` tag.
+
+You can also use this tag to create a link to a post in Markdown as follows:
+
+{% highlight html %}
+[Name of Link]({{ "{% post_url 2010-07-21-name-of-post " }}%})
+{% endhighlight %}
+
diff --git a/site/_posts/2012-07-01-troubleshooting.md b/site/_posts/2012-07-01-troubleshooting.md
new file mode 100644
index 00000000000..e6a592f2bf4
--- /dev/null
+++ b/site/_posts/2012-07-01-troubleshooting.md
@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Troubleshooting
+prev_section: contributing
+next_section: sites
+---
+
+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.
+
+## Installation Problems
+
+If you encounter errors during gem installation, you may need to install
+the header files for compiling extension modules for ruby 1.9.1. This
+can be done on Ubunutu or Debian by running:
+
+{% highlight bash %}
+sudo apt-get install ruby1.9.1-dev
+{% endhighlight %}
+
+On Red Hat, CentOS, and Fedora systems you can do this by running:
+
+{% highlight bash %}
+sudo yum install ruby-devel
+{% endhighlight %}
+
+On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the command with the following environment variable:
+
+{% highlight bash %}
+RB_USER_INSTALL=true gem install jekyll
+{% endhighlight %}
+
+On OSX, you may need to update RubyGems:
+
+{% highlight bash %}
+sudo gem update --system
+{% endhighlight %}
+
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
+## Problems running Jekyll
+
+On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in order to have the `jekyll` executable be available in your Terminal.
+
+## Base-URL Problems
+
+If you are using base-url option like `jekyll --server --base-url '/blog'` then make sure that you access the site at `http://localhost:4000/blog/index.html`. Just accessing `http://localhost:4000/blog` will not work.
+
+## Configuration problems
+
+
+The order of precedence for conflicting [configuration settings](../configuration) is as follows:
+
+1.  Command-line flags
+2.  Configuration file settings
+3.  Defaults
+
+That is: defaults are overridden by options specified in `_config.yml`, and flags specified at the command-line will override all other settings specified elsewhere.
+
+## Markup Problems
+
+The various markup engines that Jekyll uses may have some issues. This
+page will document them to help others who may run into the same
+problems.
+
+### Maruku
+
+If your link has characters that need to be escaped, you need to use
+this syntax:
+
+`![Alt text](http://yuml.me/diagram/class/[Project]->[Task])`
+
+If you have an empty tag, i.e. ``, Maruku
+transforms this into `').strip
+    end
+
+    should "render fenced code blocks" do
+      assert_equal "
puts "Hello world"\n
", @markdown.convert(
+        <<-EOS
+```ruby
+puts "Hello world"
+```
+EOS
+      ).strip  
+    end
   end
 end
diff --git a/test/test_site.rb b/test/test_site.rb
index 833d797917a..f71a95996f5 100644
--- a/test/test_site.rb
+++ b/test/test_site.rb
@@ -166,13 +166,33 @@ class TestSite < Test::Unit::TestCase
       assert_equal files, @site.filter_entries(files)
     end
 
+    context 'error handling' do
+      should "raise if destination is included in source" do
+        stub(Jekyll).configuration do
+          Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => source_dir})
+        end
+
+        assert_raise Jekyll::FatalException do
+          site = Site.new(Jekyll.configuration)
+        end
+      end
+
+      should "raise if destination is source" do
+        stub(Jekyll).configuration do
+          Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => File.join(source_dir, "..")})
+        end
+
+        assert_raise Jekyll::FatalException do
+          site = Site.new(Jekyll.configuration)
+        end
+      end
+    end
+
     context 'with orphaned files in destination' do
       setup do
         clear_dest
         @site.process
         # generate some orphaned files:
-        # hidden file
-        File.open(dest_dir('.htpasswd'), 'w')
         # single file
         File.open(dest_dir('obsolete.html'), 'w')
         # single file in sub directory
@@ -190,7 +210,6 @@ class TestSite < Test::Unit::TestCase
       end
       
       teardown do
-        FileUtils.rm_f(dest_dir('.htpasswd'))
         FileUtils.rm_f(dest_dir('obsolete.html'))
         FileUtils.rm_rf(dest_dir('qux'))
         FileUtils.rm_f(dest_dir('quux'))
@@ -201,7 +220,6 @@ class TestSite < Test::Unit::TestCase
       
       should 'remove orphaned files in destination' do
         @site.process
-        assert !File.exist?(dest_dir('.htpasswd'))
         assert !File.exist?(dest_dir('obsolete.html'))
         assert !File.exist?(dest_dir('qux'))
         assert !File.exist?(dest_dir('quux'))