Reorganized docs, added files for documenting plugins

source/docs/blogging/index.markdown

@@ -7,34 +7,38 @@ comments: false
 footer: false
 ---
 
-Create your first post.
+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.
 
-    rake new_post["hello world"]
+#### Syntax
 
-This will put a new post with a name like like `2011-07-3-hello-world.markdown` in the `source/_posts` directory.
-The filename will determine your url, and depending on your [permalink settings](https://github.com/mojombo/jekyll/wiki/Permalinks) your url may end up looking like this
-`site.com/blog/20011/07/03/hello-world/index.html`.
+  rake new_post["title"]
 
-New post expects a title and attempts to strip out undesirable url characters when creating the filename.
+`new_post` expects a naturally written title and strips out undesirable url characters when creating the filename.
+The default file extension for new posts is `markdown` but you can configure that in the `Rakefile`.
+
+#### Example
 
     rake new_post["Zombie Ninjas Attack: A survivor's retrospective"]
+
     # Creates the file
     source/_posts/2011-07-03-zombie-ninjas-attack-a-survivors-retrospective.markdown
 
-The default file extension for new posts is `markdown` but you can configure that in the `Rakefile`.
-Open up your post in a text editor and you'll see a block of [yaml front matter](https://github.com/mojombo/jekyll/wiki/yaml-front-matter)
+The filename will determine your url. With the default [permalink settings](https://github.com/mojombo/jekyll/wiki/Permalinks) the url would be something like
+`http://site.com/blog/20011/07/03/zombie-ninjas-attack-a-survivors-retrospective/index.html`.
+
+Open a post in a text editor and you'll see a block of [yaml front matter](https://github.com/mojombo/jekyll/wiki/yaml-front-matter)
 which tells Jekyll how to processes posts and pages.
 
     ---
     layout: post
-    title: "Hello World"
+    title: "Zombie Ninjas Attack: A survivor's retrospective"
     date: 2011-07-03 5:59
     comments: true
     categories:
     ---
 
-If you like, you can turn comments off, add categories for your post. Beneath the yaml block, go ahead and type up a sample post, or use some [inspired filler](http://baconipsum.com/).
-After you've saved that post you'll want to generate your blog.
+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.
 
 ### Generate & Preview
 
@@ -42,7 +46,7 @@ After you've saved that post you'll want to generate your blog.
     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 webbrick server is handy, but if you're a [POW](http://pow.cx) user, you can set it up to work with Octopress like this.
+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
@@ -55,19 +59,19 @@ Now that you're setup with POW, you'll just run `rake watch` and load up `http:/
 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.
 
-    rake new_page[awesome]
+    rake new_page[super-awesome]
     # creates
-    /source/awesome/index.markdown
+    /source/super-awesome/index.markdown
 
-    rake new_page[awesome/page.html]
+    rake new_page[super-awesome/page.html]
     # creates
-    /source/awesome/page.html
+    /source/super-awesome/page.html
 
 Like with the new post task, the default file extension is `markdown` but you can configure that in the `Rakefile`. A freshly generated page might look like this:
 
     ---
     layout: page
-    title: "Awesome"
+    title: "Super Awesome"
     date: 2011-07-03 5:59
     comments: true
     sharing: true

source/docs/blogging/plugins/index.markdown

@@ -0,0 +1,11 @@
+---
+layout: page
+title: "Plugins"
+date: 2011-07-22 11:18
+sidebar: false
+footer: false
+---
+
+## Blockquotes
+
+{% render_partial docs/plugins/blockquote.markdown %}

source/docs/configuring/index.markdown

@@ -6,7 +6,7 @@ sidebar: false
 footer: false
 ---
 
-[« Previous, Deploying Octopress](/docs/deploy)
+[« Previous, Octopress Setup](/docs/setup)
 
 I've tried to keep configuring Octopress fairly simple and you'll probably only ever change the `Rakefile` and the `_config.yml`.
 Here's a list of files for configuring Octopress.
@@ -23,19 +23,19 @@ Configurations in the `Rakefile` are mostly related to deployment and you probab
 ## Blog Configuration
 
 In the `_config.yml` there are three sections for configuring your Octopress Blog.
-**Spoiler:** You'll probably only change `url`, `title`, `subtitle` and `author` and enable some 3rd party services.
+**Spoiler:** You must change `url`, and you'll probably change `title`, `subtitle` and `author` and enable some 3rd party services.
 
 ### Main Configs
 
 {% codeblock %}
-url:                # For rewriting URLs for RSS, etc
+url:                # For rewriting urls for RSS, etc
 title:              # Used in the header and title tags
 
 subtitle:           # A description used in the header
 author:             # Your name, for RSS, Copyright, Metadata
 simple_search:      # Search engine for simple site search
-subscribe_rss:      # URL for your blog's feed, defauts to /atom.xml
-subscribe_email:    # URL to subscribe by email (service required)
+subscribe_rss:      # Url for your blog's feed, defauts to /atom.xml
+subscribe_email:    # Url to subscribe by email (service required)
 email:              # Email address for the RSS feed if you want it.
 {% endcodeblock %}
 
@@ -47,7 +47,7 @@ These configurations are used by Jekyll and Plugins. If you're not familiar with
 
 {% codeblock %}
 root:             # Mapping for relative urls (default: /)
-port:             # Port to mount Jekyll's webbrick server
+port:             # Port to mount Jekyll's WEBrick server
 permalink:        # Permalink structure for blog posts
 source:           # Directory for site source files
 destination:      # Directory for generated site files
@@ -61,9 +61,9 @@ recent_posts:     # Number of recent posts to appear in the sidebar
 
 If you want to change the way permalinks are written for your blog posts, see [Jekyll's permalink docs](https://github.com/mojombo/jekyll/wiki/Permalinks).
 
-**Note:** Jekyll has a `baseurl` config which adds a redirect for Jekyll's webbrick server for shallow subdirectory support.
-Octopress uses the `root` configuration and offers a rake task `set_root_dir[/some/directory]` to update configs and move exported files to the subdirectory [(see Deploying Octopress)](/docs/deploying).
-In other words, don't use `baseurl` use `root`.
+**Note:** Jekyll has a `baseurl` config which adds a redirect for Jekyll's WEBrick server for subdirectory support. This works fine if you want
+to use the WEBrick server, but for any other web service you have to add support for the redirect. Instead, Octopress uses the `root` config and offers a rake task
+`set_root_dir[/some/directory]` which moves the output directory into a subdirectory and updates configurations. [(see Deploying Octopress)](/docs/deploying).
 
 ### 3rd Party Settings
 These third party integrations are already set up for you. Simply fill in the configurations and they'll be added to your site.
@@ -75,4 +75,6 @@ These third party integrations are already set up for you. Simply fill in the co
 - **Disqus Comments** - Add your disqus short name to enable disqus comments on your site.
 - **Google Analytics** - Add your tracking id to enable Google Analytics tracking for your site.
 
-[Next, Blogging With Octopress »](/docs/blogging)
+The Octopress layouts read these configurations and only include the javascript and html necessary for the enabled services.
+
+[Next, Deploying Octopress »](/docs/deploying)

source/docs/deploying/index.markdown

@@ -6,7 +6,7 @@ sidebar: false
 footer: false
 ---
 
-[« Previous, Octopress Setup](/docs/setup)
+[« Previous, Configuring Octopress](/docs/configuring)
 
 ### Deploying with Rsync via SSH
 
@@ -80,4 +80,4 @@ Here's an example for deploying the Octopress website to Github Project Pages:
 
 For more info on deploying a Jekyll Blog, checkout [Jekyll's deployment wiki page](https://github.com/mojombo/jekyll/wiki/Deployment).
 
-[Next, Configuring Octopress »](/docs/configuring)
+[Next, Blogging With Octopress »](/docs/blogging)

source/docs/index.markdown

@@ -14,15 +14,15 @@ Jekyll at its core is a text transformation engine. The concept behind the syste
 {% endblockquote %}
 
 ## Getting Started
-- [Initial setup](/docs/setup)
-- [Deploying Octopress](/docs/deploying)
-- [Basic Configuration](/docs/configuring)
+- [Initial setup](/docs/setup) - Get source and install dependencies
+- [Basic Configuration](/docs/configuring) - A descriptive list of configurations
+- [Deploying Octopress](/docs/deploying) - Simple deploy instructions for Rsync and Github pages
 
 ## Using Octopress
 - [Blogging Basics](/docs/blogging)
 - [Sharing Code Snippets](/docs/blogging/code)
 - [Syntax Highlighting Test](/docs/blogging/code/test)
-- TODO [Blogging With Plugins](/docs/blogging/plugins)
+- [Blogging With Plugins](/docs/blogging/plugins)
 - TODO [Theming & Customization](/docs/theming)
 - TODO [Updating](/docs/updating)
 
@@ -30,7 +30,7 @@ Jekyll at its core is a text transformation engine. The concept behind the syste
 - Code Block
 - Include Code
 - Gist Tag
-- Include Partial
+- Render Partial
 - Figure Tag
 - Blockquote
 - Pullquote
@@ -38,6 +38,6 @@ Jekyll at its core is a text transformation engine. The concept behind the syste
 - Sitemap Generator
 - Category Generator
 - Compass Compiler
-- Haml Convertor
+- Haml Converter
 - Pygments Cache
 - Titlecase

source/docs/plugins/blockquote.markdown

@@ -0,0 +1,63 @@
+---
+layout: page
+title: "Blockquote"
+date: 2011-07-22 09:15
+sidebar: false
+footer: false
+---
+
+The blockquote plugin takes and author, source, title and quote, and outputs semantic HTML.
+
+#### Syntax
+
+    {{ "{% blockquote [author[, source]] [link] [source_link_title]" }} %}
+    Quote string
+    {{ "{% endblockquote" }} %}
+
+You'll notice there are two entries for `source`; one after `author`, and one after `link`. If you are citing from a printed work or a speech or something you cannot link to,
+use the first method `Author's Name, Cited Work`. If you're going to link to the work, omit the first source method, and add a source title after the link `Author's Name http://source.com Article title`.
+
+#### Examples
+Blockquote arguments are optional, you can output a plain blockquote like this.
+
+    {{ "{% blockquote" }} %}
+    Last night I lay in bed looking up at the stars in the sky and I thought to myself, where the heck is the ceiling.
+    {{ "{% endblockquote" }} %}
+
+{% blockquote %}
+Last night I lay in bed looking up at the stars in the sky and I thought to myself, where the heck is the ceiling.
+{% endblockquote %}
+
+**Quote from a printed work.**
+
+    {{ "{% blockquote Douglas Adams, The Hichhikers Guide to the Galaxy" }} %}
+    Flying is learning how to throw yourself at the ground and miss.
+    {{ "{% endblockquote" }} %}
+
+{% blockquote Douglas Adams, The Hitchhikers Guide to the Galaxy %}
+Flying is learning how to throw yourself at the ground and miss.
+{% endblockquote %}
+
+**Quote from Twitter**
+
+    {{ "{% blockquote @allanbranch https://twitter.com/allanbranch/status/90766146063712256" }} %}
+    Over the past 24 hours I've been reflecting on my life & I've realized only one thing. I need a medieval battle axe.
+    {{ "{% endblockquote" }} %}
+
+{% blockquote @allanbranch https://twitter.com/allanbranch/status/90766146063712256 %}
+Over the past 24 hours I've been reflecting on my life & I've realized only one thing. I need a medieval battle axe.
+{% endblockquote %}
+
+**Quote from an article on the web**
+
+    {{ "{% Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing" }} %}
+    Every interaction is both precious and an opportunity to delight.
+    {{ "{% endblockquote" }} %}
+
+{% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %}
+Every interaction is both precious and an opportunity to delight.
+{% endblockquote %}
+
+For those who appreciate the little things, you'll notice in the Twitter example above, the url is truncated and drops the protocol segment.
+Sometimes (like with Twitter) ading a link title doesn't really make sense, but showing the full url is noisy and distracting.
+For this reason, the blockquote plugin automatically strips out the protocol, and if the url is longer than 32 characters it truncates the url on a forward slash for beauty's sake.

source/docs/plugins/category_generator.markdown

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

source/docs/plugins/codeblock.markdown

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

source/docs/plugins/compass_compiler.markdown

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

source/docs/plugins/figure_tag.markdown

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

source/docs/plugins/filters.markdown

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

source/docs/plugins/gist_tag.markdown

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

source/docs/plugins/haml_converter.markdown

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

source/docs/plugins/include_code.markdown

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

source/docs/plugins/pullquote.markdown

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

source/docs/plugins/pygments_cache.markdown

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

source/docs/plugins/render_partial.markdown

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

source/docs/plugins/sitemap.markdown

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

source/docs/plugins/titlecase.markdown

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