updated and reorganized docs

Rakefile

@@ -59,12 +59,13 @@ end
 desc "Begin a new post in #{source_dir}/#{posts_dir}"
 task :new_post, :title do |t, args|
   require './plugins/titlecase.rb'
+  mkdir_p "#{source_dir}/#{posts_dir}"
   args.with_defaults(:title => 'new-post')
   title = args.title
   filename = "#{source_dir}/#{posts_dir}/#{Time.now.strftime('%Y-%m-%d')}-#{title.downcase.gsub(/&/,'and').gsub(/[,'":\?!\(\)\[\]]/,'').gsub(/[\W\.]/, '-').gsub(/-+$/,'')}.#{new_post_ext}"
   puts "Creating new post: #{filename}"
   open(filename, 'w') do |post|
-    system "mkdir -p #{source_dir}/#{posts_dir}";
+    system "mkdir -p #{source_dir}/#{posts_dir}/";
     post.puts "---"
     post.puts "layout: post"
     post.puts "title: \"#{title.gsub(/&/,'&').titlecase}\""

source/_includes/head.html

@@ -22,10 +22,11 @@
   <link href="{{ root_url }}/favicon.png" rel="shortcut icon" />
   <link href="{{ root_url }}/stylesheets/screen.css" media="screen, projection" rel="stylesheet" type="text/css">
   <script src="{{ root_url }}/javascripts/modernizr-2.0.js"></script>
-  <script src="http://s3.amazonaws.com/ender-js/jeesh.min.js"></script>
+  <script src="{{ root_url }}/javascripts/ender.js"></script>
+  <!--<script src="http://s3.amazonaws.com/ender-js/jeesh.min.js"></script>-->
   <script src="{{ root_url }}/javascripts/octopress.js" type="text/javascript"></script>
-  <link href='http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>
+  <!--<link href='http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>-->
-  <link href='http://fonts.googleapis.com/css?family=PT+Sans:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>
+  <!--<link href='http://fonts.googleapis.com/css?family=PT+Sans:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>-->
   <link href="{{ root_url }}/atom.xml" rel="alternate" title="{{site.title}}" type="application/atom+xml"/>
   {% include google_analytics.html %}
   {% include google_plus_one.html %}

source/_posts

@@ -1 +0,0 @@
-/Users/bmathis/Dropbox/octopress/_assets/source/_posts

source/_posts/2011-07-22-octopress-20-surfaces.markdown

@@ -0,0 +1,15 @@
+---
+layout: post
+title: "Octopress 2.0 Surfaces"
+date: 2011-07-22 14:44
+comments: true
+categories: release
+---
+
+Octopress is a framework designed for Jekyll, the static blogging engine powering Github Pages. So what is Jekyll?
+
+{% blockquote Jekyll Wiki https://github.com/mojombo/jekyll/wiki/Usage %}
+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.
+{% endblockquote %}
+
+

source/docs/blogging/code/index.markdown

@@ -28,86 +28,11 @@ them to the Vim rendered versions.
 
 Check out the [test page](/docs/blogging/code/test) to see the results.
 
-## Gist Code embedding
+## Gist Embedding
-All you need is the gist's id and you can easily embed it in your page. This actually downloads a cache of the gist and embeds it in a `<noscript>` tag for RSS
+{% render_partial docs/plugins/gist-tag/index.markdown %}
-readers and search engines, while still using Github's javascript gist embed code for browsers.
-
-#### Syntax
-
-    {{ "{% gist gist_id [filename]" }} %}
-
-#### Example
-
-    {{ "{% gist 996818" }} %}
-
-{% gist 996818 %}
-
-If you have a gist with multiple files, you can include files one at a time by adding the name after the gist id.
-
-    {{ "{% gist 1059334 svg_bullets.rb" }} %}
-    {{ "{% gist 1059334 usage.scss" }} %}
 
 ## Include Code Snippets
-Import files on your filesystem into any blog post as embedded code snippets with syntax highlighting and a download link.
+{% render_partial docs/plugins/include-code/index.markdown %}
-In the `_config.yml` you can set your `code_dir` but the default is `source/downloads/code`. Simply put a file anywhere under that directory and
-use the following tag to embed it in a post.
 
-#### Syntax
+## Inline Code Blocks
-
+{% render_partial docs/plugins/codeblock/index.markdown %}
-    {{ "{% include_code [title] url" }} %}
-
-#### Example 1
-
-    {{ "{% include_code javascripts/test.js" }} %}
-
-#### Example 2 (with optional title)
-
-    {{ "{% include_code Testing include_code javascripts/test.js" }} %}
-
-This includes a file from `source/downloads/code/javascripts/test.js`. By default the `<figcaption>` will be the filename, but you can add a title before the filepath if you like.
-
-#### Demo of Example 2
-
-{% include_code Testing include_code javascripts/test.js %}
-
-## Inline Codeblocks
-You can also write blocks of code directly in your posts.
-
-#### Syntax
-
-    {{ "{% codeblock [title] [url] [link text]" }} %}
-
-#### Example 1
-
-    {{ "{% codeblock" }} %}
-    Awesome code snippet
-    {{ "{% endcodeblock" }} %}
-
-{% codeblock %}
-Awesome code snippet
-{% endcodeblock %}
-
-#### Example 2
-
-    # Including a file extension in the title enables highlighting
-    {{ "{% codeblock Time to be Awesome - awesome.rb" }} %}
-    puts "Awesome!" unless lame
-    {{ "{% endcodeblock" }} %}
-
-{% codeblock Time to be Awesome - awesome.rb %}
-puts "Awesome!" unless lame
-{% endcodeblock %}
-
-#### Example 3
-
-    # Add an optional URL to enable downloading or linking to source
-    {{ "{% codeblock Got pain? painreleif.sh http://example.com/painreleief.sh Download it!" }} %}
-    $ rm -rf ~/PAIN
-    {{ "{% endcodeblock" }} %}
-
-{% codeblock Javascript Array Syntax (array.js) https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array MDN Documentation %}
-var arr1 = new Array(arrayLength);
-var arr2 = new Array(element0, element1, ..., elementN);
-{% endcodeblock %}
-
-The last argument `link_text` is optional. You may want to link to a source for download file, or documentation on some other site.

source/docs/blogging/index.markdown

@@ -7,7 +7,13 @@ comments: false
 footer: false
 ---
 
-Jekyll has some conventions for blog post file names which are a bit of a pain to manage manually, so Octopress ships with a rake task to make that easier.
+Octopress offers some rake tasks to create post and pages preloaded with metadata and according to Jekyll's naming conventions.
+
+## Blog Posts
+Blog posts must be stored in the `source/_posts` directory and named according to Jekyll's naming conventions: `YYYY-MM-DD-post-title.markdown`. The name of the file is
+used as the slug for the url, and the date helps with file distinction and determines the sorting order for post loops.
+
+Octopress provides a rake task to create new blog posts with the right naming conventions, with sensible yaml metadata.
 
 #### Syntax
 
@@ -38,23 +44,9 @@ which tells Jekyll how to processes posts and pages.
     ---
 
 Here you can turn comments off and or categories to your post. If you are working on a multi-author blog, you can add `author: Your Name` to the
-metadata for proper attribution on a post.
+metadata for proper attribution on a post. If you are working on a draft, you can add `published: false` to prevent it from being posted when you generate your blog.
 
-### Generate & Preview
+## New Pages
-
-    rake generate   # Generates posts and pages into the public directory
-    rake watch      # Watches source/ and sass/ for changes and regenerates
-    rake preview    # Watches, and mounts a webserver at http://localhost:4000
-
-Jekyll's built in WEBrick server is handy, but if you're a [POW](http://pow.cx) user, you can set it up to work with Octopress like this.
-
-    cd ~/.pow
-    ln -s /path/to/octopress
-    cd -
-
-Now that you're setup with POW, you'll just run `rake watch` and load up `http://octopress.dev` instead.
-
-### Pages
 
 You can add pages anywhere in your blog source directory and they'll be parsed by Jekyll. The URL will correspond directly to the filepath, so `about.markdown` will become `site.com/about.html`. If you prefer the URL `site.com/about/` you'll want to create the page as `about/index.markdown`.
 Octopress has a rake task for creating new pages easily.
@@ -80,4 +72,18 @@ Like with the new post task, the default file extension is `markdown` but you ca
 
 The title is derived from the filename so you'll likely want to change that. This is very similar to the post yaml except it doesn't include categories, and you can toggle sharing and comments or remove the footer altogehter. If you don't want to show a date on your page, just remove it from the yaml.
 
+## Generate & Preview
+
+    rake generate   # Generates posts and pages into the public directory
+    rake watch      # Watches source/ and sass/ for changes and regenerates
+    rake preview    # Watches, and mounts a webserver at http://localhost:4000
+
+Jekyll's built in WEBrick server is handy, but if you're a [POW](http://pow.cx) user, you can set it up to work with Octopress like this.
+
+    cd ~/.pow
+    ln -s /path/to/octopress
+    cd -
+
+Now that you're setup with POW, you'll just run `rake watch` and load up `http://octopress.dev` instead.
+
 [Next, Sharing Code Snippets »](/docs/blogging/code)

source/docs/blogging/plugins/index.markdown

@@ -6,6 +6,21 @@ sidebar: false
 footer: false
 ---
 
-## Blockquotes
+## Block quote
 
-{% render_partial docs/plugins/blockquote.markdown %}
+{% blockquote @AustinTaylor https://twitter.com/austintaylor/status/73136957617750016 %}
+Give a man a fish, he'll have food for a day. Teach a man to fish, and he'll always come to you with his fishing problems.
+{% endblockquote %}
+
+[Examples & documentation »](/docs/plugins/blockquotes/)
+
+## Pull quote
+
+Octopress offers a CSS3 only technique for pull quotes, based on the technique by [Maykel Loomans](http://miekd.com/articles/pull-quotes-with-html5-and-css/).
+
+{% pullquote %}
+When writing longform posts, I find it helpful to include pull quotes to help readers easily identify the topics covered in each section. Some prefer to break things up with lots of headings, and while this seems to be a trend it doesn't work so well for long form prose.
+It is important to note that {" pull quotes are merely visual in presentation and should not appear twice in the text. "} That is why it a CSS only technique for styling pull quotes is preferable. Octopress includes a handy pull quote plugin to make this easy for you.
+{% endpullquote %}
+
+[Examples & documentation »](/docs/plugins/blockquotes/)

source/docs/index.markdown

@@ -7,11 +7,9 @@ comments: false
 footer: false
 ---
 
-Octopress is a framework designed for Jekyll, the static blogging engine powering Github Pages. So what is Jekyll?
+Octopress is a framework designed for Jekyll, the static blogging engine powering Github Pages. Have a look through
-
+the documentation and if you have trouble, [I'll be happy to help](http://convore.com/octopress/support). If you find errors
-{% blockquote Jekyll Wiki https://github.com/mojombo/jekyll/wiki/Usage %}
+[post an issue](https://github.com/imathis/octopress/issues) or fork and send a pull request on the [site branch](https://github.com/imathis/octopress/tree/site).
-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.
-{% endblockquote %}
 
 ## Getting Started
 - [Initial setup](/docs/setup) - Get source and install dependencies
@@ -19,25 +17,25 @@ Jekyll at its core is a text transformation engine. The concept behind the syste
 - [Deploying Octopress](/docs/deploying) - Simple deploy instructions for Rsync and Github pages
 
 ## Using Octopress
-- [Blogging Basics](/docs/blogging)
+- [Blogging Basics](/docs/blogging) - Creating blog posts and pages
-- [Sharing Code Snippets](/docs/blogging/code)
+- [Sharing Code Snippets](/docs/blogging/code) - Share code snippets with ease
-- [Syntax Highlighting Test](/docs/blogging/code/test)
+- [Syntax Highlighting Test](/docs/blogging/code/test) - Language highlighting tests
-- [Blogging With Plugins](/docs/blogging/plugins)
+- [Blogging With Plugins](/docs/blogging/plugins) - Overview of plugins for blogging
-- TODO [Theming & Customization](/docs/theming)
+- TODO [Theming & Customization](/docs/theming) - Guide to making changes to your Octopress theme
-- TODO [Updating](/docs/updating)
+- TODO [Updating](/docs/updating) - A guide to help you stay up to date
 
 ## Octopress Plugins - Usage & Examples
-- Code Block
+- [Code Block](/docs/plugins/codeblock) - For easy inline code sharing
-- Include Code
+- [Include Code](/docs/plugins/include-code) - Embed code from your filesystem
-- Gist Tag
+- [Gist Tag](/docs/plugins/gist-tag) - Automatically downloads and embeds Github gists
-- Render Partial
+- [Render Partial](/docs/plugins/render-partial) - Insert any file into another post or page.
-- Figure Tag
+- [Figure Tag](/docs/plugins/figure-tag) - Easily post images with semantic <figure> & <figcaption> elements
-- Blockquote
+- [Blockquote](/docs/plugins/blockquote) - Generate beautiful, semantic block quotes
-- Pullquote
+- [Pullquote](/docs/plugins/pullquote) - Generate CSS only pull quotes — no duplicate data, no javascript.
-- Custom filters
+- [Custom filters](/docs/plugins/octopress-filters) - Liquid filters built just for Octopress
-- Sitemap Generator
+- [Category Generator](/docs/plugins/category-generator) - Generates archive pages for each blog category
-- Category Generator
+- Sitemap Generator - Generates an SEO friendly sitemap.xml
-- Compass Compiler
+- Compass Compiler - Forces Jekyll to compile Compass on each load
-- Haml Converter
+- Haml Converter - Allows .haml pages to be processed by Jekyll
-- Pygments Cache
+- Pygments Cache - Caches code snippets to speed up Jekyll processing
-- Titlecase
+- Titlecase - Required by several plugins to automatically generate proper title captalization

source/docs/plugins/codeblock.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Codeblock"
-date: 2011-07-22 09:13
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/codeblock/index.markdown

@@ -0,0 +1,48 @@
+---
+layout: page
+title: "Codeblock"
+date: 2011-07-22 09:13
+sidebar: false
+footer: false
+---
+
+With this plugin you can write blocks of code directly in your posts and optionally add titles or links.
+
+#### Syntax
+
+    {{ "{% codeblock [title] [url] [link text]" }} %}
+
+#### Example 1
+
+    {{ "{% codeblock" }} %}
+    Awesome code snippet
+    {{ "{% endcodeblock" }} %}
+
+{% codeblock %}
+Awesome code snippet
+{% endcodeblock %}
+
+#### Example 2
+
+    # Including a file extension in the title enables highlighting
+    {{ "{% codeblock Time to be Awesome - awesome.rb" }} %}
+    puts "Awesome!" unless lame
+    {{ "{% endcodeblock" }} %}
+
+{% codeblock Time to be Awesome - awesome.rb %}
+puts "Awesome!" unless lame
+{% endcodeblock %}
+
+#### Example 3
+
+    # Add an optional URL to enable downloading or linking to source
+    {{ "{% codeblock Got pain? painreleif.sh http://example.com/painreleief.sh Download it!" }} %}
+    $ rm -rf ~/PAIN
+    {{ "{% endcodeblock" }} %}
+
+{% codeblock Javascript Array Syntax (array.js) https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array MDN Documentation %}
+var arr1 = new Array(arrayLength);
+var arr2 = new Array(element0, element1, ..., elementN);
+{% endcodeblock %}
+
+The last argument `link_text` is optional. You may want to link to a source for download file, or documentation on some other site.

source/docs/plugins/compass_compiler.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Compass Compiler"
-date: 2011-07-22 09:18
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/gist-tag/index.markdown

@@ -0,0 +1,26 @@
+---
+layout: page
+title: "Gist Tag"
+date: 2011-07-22 09:13
+sidebar: false
+footer: false
+---
+
+All you need is the gist's id and you can easily embed it in your page. This actually downloads a cache of the gist and embeds it in a `<noscript>` tag for RSS
+readers and search engines, while still using Github's javascript gist embed code for browsers.
+
+#### Syntax
+
+    {{ "{% gist gist_id [filename]" }} %}
+
+#### Example
+
+    {{ "{% gist 996818" }} %}
+
+{% gist 996818 %}
+
+If you have a gist with multiple files, you can include files one at a time by adding the name after the gist id.
+
+    {{ "{% gist 1059334 svg_bullets.rb" }} %}
+    {{ "{% gist 1059334 usage.scss" }} %}
+

source/docs/plugins/gist_tag.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Gist Tag"
-date: 2011-07-22 09:13
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/haml_converter.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Haml Converter"
-date: 2011-07-22 09:18
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/include-code/index.markdown

@@ -0,0 +1,29 @@
+---
+layout: page
+title: "Include Code"
+date: 2011-07-22 09:13
+sidebar: false
+footer: false
+---
+
+Import files on your filesystem into any blog post as embedded code snippets with syntax highlighting and a download link.
+In the `_config.yml` you can set your `code_dir` but the default is `source/downloads/code`. Simply put a file anywhere under that directory and
+use the following tag to embed it in a post.
+
+#### Syntax
+
+    {{ "{% include_code [title] url" }} %}
+
+#### Example 1
+
+    {{ "{% include_code javascripts/test.js" }} %}
+
+#### Example 2 (with optional title)
+
+    {{ "{% include_code Testing include_code javascripts/test.js" }} %}
+
+This includes a file from `source/downloads/code/javascripts/test.js`. By default the `<figcaption>` will be the filename, but you can add a title before the filepath if you like.
+
+#### Demo of Example 2
+
+{% include_code Testing include_code javascripts/test.js %}

source/docs/plugins/include_code.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Include Code"
-date: 2011-07-22 09:13
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/pygments_cache.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Pygments Cache"
-date: 2011-07-22 09:19
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/sitemap.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Sitemap"
-date: 2011-07-22 09:16
-comments: true
-sharing: true
-footer: true
----

source/docs/plugins/titlecase.markdown

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Titlecase"
-date: 2011-07-22 09:19
-comments: true
-sharing: true
-footer: true
----