updated configuration docs

source/docs/configuring/index.markdown

@@ -8,44 +8,62 @@ footer: false
 
 [« Previous, Deploying Octopress](/docs/deploy)
 
-I've tried to keep configuring Octopress fairly simple and Octopress keeps most configurations in two places, the `Rakefile` and the `_config.yml`.
+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.
 
-    _config.yml       # Main config (Jekyll's settings)
+{% codeblock %}
-    Rakefile          # Configs for deployment
+_config.yml       # Main config (Jekyll's settings)
-    config.rb         # Compass config
+Rakefile          # Configs for deployment
-    config.ru         # Rack config
+config.rb         # Compass config
+config.ru         # Rack config
+{% endcodeblock %}
 
 Configurations in the `Rakefile` are mostly related to deployment and you probably won't have to touch them unless you're using rsync.
 
 ## 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.
 
 ### Main Configs
 
-- **url** - Your blog's full published url. This lets Octopress automatically rewrite relative urls to absolute urls for the RSS feed.
+{% codeblock %}
-- **title** - Your blog's title is used in the header and title tag for your pages.
+url:                # For rewriting URLs for RSS, etc
-- **subtitle** - A further description for your blog. This appears beneath the Main header.
+title:              # Used in the header and title tags
-- **author** - Your name (for RSS, Copyright, and metadata) If this is a multi-author blog, you can set author in the yaml front matter of each blog post instead.
+
-- **simple_search** - Queries entered in the search form, are constructed as a site search query eg. `search phrase site:yoursite.com`. Here you can set the search engine it uses (defaults to Google).
+subtitle:           # A description used in the header
-- **subscribe_rss** - Enter a url for your blog's RSS feed Defaults to `/atom.xml` an ATOM feed generated by Octopress
+author:             # Your name, for RSS, Copyright, Metadata
-- **subscribe_email** - Enter a url for your blog's email subscription link (if you have one). Octopress does not provide this.
+simple_search:      # Search engine for simple site search
-- **email** - (Optional) fills in the email property of the RSS feed.
+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 %}
+
+**Note:** If your site is a multi-author blog, you may want to set this config's `author` to the name of your
+company or project, and add author metadata to posts and pages to give proper attribution for those works.
 
 ### Jekyll & Plugins
-If you're not familiar with Jekyll, you should probably have a look at the [configuration docs](https://github.com/mojombo/jekyll/wiki/Configuration)
+These configurations are used by Jekyll and Plugins. If you're not familiar with Jekyll, you should probably have a look at the [configuration docs](https://github.com/mojombo/jekyll/wiki/Configuration) which lists more options that aren't covered here.
 
-- **root** - Leave this blank unless you're deploying to a subdirectory. For more info see [Deploying Octopress](/setup/deploy/)
+{% codeblock %}
-- **port** - Specify a port for Jekyll's built in webbrick server.
+root:             # Mapping for relative urls (default: /)
-- **permalink** - See [Jekyll's permalink docs](https://github.com/mojombo/jekyll/wiki/Permalinks) if you want to change the way permalinks are written for your blog posts.
+port:             # Port to mount Jekyll's webbrick server
-- **source** - The source directory for your blog, no need to change this.
+permalink:        # Permalink structure for blog posts
-- **destination** - The folder where the generated blog files will be written.
+source:           # Directory for site source files
-- **plugins** - The plugins directory.
+destination:      # Directory for generated site files
-- **markdown** - Choose your Markdown processor (rdiscount or kramdown).
+plugins:          # Directory for Jekyll plugins
-- **pygments** - Enable or disable pygments syntax highlighting.
+code_dir:         # Directory for code snippets (for include_code plugin)
-- **paginate** - Set the number of posts per page in your blog index.
+category_dir:     # Directory for generated blog category pages
-- **recent_posts** - Set the number of recent posts to appear in the sidebar section.
+pygments:         # Toggle pygments syntax highlighting
+paginate:         # Posts per page on the blog index
+recent_posts:     # Number of recent posts to appear in the sidebar
+{% endcodeblock %}
+
+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`.
 
 ### 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.