diff --git a/README.md b/README.md
index 000e4d8b0..78bcc5a60 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,429 @@
-hugo
-====
+# Hugo
-A Fast and Flexible Static Site Generator built with love by spf13 in GoLang
+A really fast static site generator written in GoLang.
+
+## Overview
+
+Hugo is a static site generator written in GoLang. It is optimized for
+speed, easy use and configurability. Hugo takes a directory with content and
+templates and renders them into a full html website.
+
+Hugo makes use of markdown files with front matter for meta data.
+
+A typical website of moderate size can be
+rendered in a fraction of a second. It is written to work well with any
+kind of website including blogs, tumbles and docs.
+
+
+# Getting Started
+
+## Installing Hugo
+
+Installation is very easy. Simply download the appropriate version for your
+platform. Hugo is written in GoLang with support for Windows, Linux and OSX.
+
+Please make sure that you place the executable in your path. `/usr/local/bin`
+is the most probable location.
+
+Hugo doesn't have any external dependencies, but can benefit from external
+programs.
+
+## Source Directory Organization
+
+Hugo takes a single directory and uses it as the input for creating a complete website.
+
+Hugo has a very small amount of configuration, while remaining highly customizable.
+It accomplishes by assuming that you will only provide templates with the intent of
+using them.
+
+An example directory may look like:
+
+ .
+ ├── config.json
+ ├── content
+ | ├── post
+ | | ├── firstpost.md
+ | | └── secondpost.md
+ | └── quote
+ | | ├── first.md
+ | | └── second.md
+ ├── layouts
+ | ├── chrome
+ | | ├── header.html
+ | | └── footer.html
+ | ├── indexes
+ | | ├── category.html
+ | | ├── post.html
+ | | ├── quote.html
+ | | └── tag.html
+ | ├── post
+ | | ├── li.html
+ | | ├── single.html
+ | | └── summary.html
+ | ├── quote
+ | | ├── li.html
+ | | ├── single.html
+ | | └── summary.html
+ | ├── shortcodes
+ | | ├── img.html
+ | | ├── vimeo.html
+ | | └── youtube.html
+ | ├── index.html
+ | └── rss.xml
+ └── public
+
+This directory structure tells us a lot about this site:
+
+1. the website intends to have two different types of content, posts and quotes.
+2. It will also apply two different indexes to that content, categories and tags.
+3. It will be displaying content in 3 different views, a list, a summary and a full page view.
+
+Included with the repository is an example site ready to be rendered.
+
+## Configuration
+
+The directory structure and templates provide the majority of the
+configuration for a site. In fact a config file isn't even needed for many websites
+since the defaults used follow commonly used patterns.
+
+The following is an example of a config file with the default values
+
+ {
+ "SourceDir" : "content",
+ "LayoutDir" : "layouts",
+ "PublishDir" : "public",
+ "BuildDrafts" : false,
+ "Tags" : { "category" : "categories", "tag" : "tags" },
+ "BaseUrl" : "http://yourSite.com/"
+ }
+
+## Usage
+Make sure either hugo is in your path or provide a path to it.
+
+ $ hugo --help
+ usage: hugo [flags] []
+ -b="": hostname (and path) to the root eg. http://spf13.com/
+ -c="config.json": config file (default is path/config.json)
+ -d=false: include content marked as draft
+ -h=false: show this help
+ -k=false: analyze content and provide feedback
+ -p="": filesystem path to read files relative from
+ -w=false: watch filesystem for changes and recreate as needed
+ -s=false: a (very) simple webserver
+ -p="1313": port for webserver to run on
+
+The most common use is probably to run hugo with your current
+directory being the input directory.
+
+
+ $ hugo
+ > X pages created
+ > Y indicies created
+
+
+If you are working on things and want to see the changes
+immediately, tell Hugo to watch for changes. **It will
+recreate the site faster than you can tab over to
+your browser to view the changes.**
+
+ $ hugo -p ~/mysite -w
+
+
+# Layout
+
+Hugo is very flexible about how you organize and structure your content.
+
+## Templates
+
+Hugo uses the excellent golang html/template library for it's template engine. It is an extremely
+lightweight engine that provides a very small amount of logic. In our
+experience that it is just the right amount of logic to be able to create a good static website
+
+This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/)
+provide a good introduction.
+
+### Template roles
+
+There are 5 different kinds of templates that Hugo works with.
+
+#### index.html
+This file must exist in the layouts directory. It is the template used to render the
+homepage of your site.
+
+#### rss.xml
+This file must exist in the layouts directory. It will be used to render all rss documents.
+The one provided in the example application will generate an ATOM format.
+
+*Important: Hugo will automatically add the following header line to this file.*
+
+
+
+#### Indexes
+An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
+pages are good examples of indexes.
+
+
+#### Content Type(s)
+Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability
+to render content in a variety of ways as determined by the type.
+
+#### Chrome
+Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice
+it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may
+likely find beneficial. As you create the rest of your templates you will include templates from the
+/layout/chrome directory. I've found it helpful to include a header and footer template
+in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html).
+
+### Adding a new content type
+
+Adding a type is easy.
+
+**Step 1:**
+Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
+
+**Step 2:**
+Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
+
+**Step 3:**
+Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
+
+**Step 4:**
+Many sites support rendering content in a few different ways, for instance a single page view and a
+summary view to be used when displaying a list of contents on a single page. Hugo makes no assumptions
+here about how you want to display your content, and will support as many different views of a content
+type as your site requires. All that is required for these additional views is that a template
+exists in each layout/type directory with the same name.
+
+For these, reviewing the example site will be very helpful in order to understand how these types work.
+
+## Variables
+
+Hugo makes a set of values available to the templates. Go templates are context based. The following
+are available in the context for the templates.
+
+**.Title** The title for the content.
+**.Description** The description for the content.
+**.Keywords** The meta keywords for this content.
+**.Date** The date the content is published on.
+**.Indexes** These will use the field name of the plural form of the index (see tags and categories above)
+**.Permalink** The Permanent link for this page.
+**.FuzzyWordCount** The approximate number of words in the content.
+**.RSSLink** Link to the indexes' rss link
+
+Any value defined in the front matter, including indexes will be made available under `.Params`.
+Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
+
+**.Params.Tags**
+**.Params.Categories**
+
+Also available is `.Site` which has the following:
+
+**.Site.BaseUrl** The base URL for the site as defined in the config.json file.
+**.Site.Indexes** The names of the indexes of the site.
+**.Site.LastChange** The date of the last change of the most recent content.
+**.Site.Recent** Array of all content ordered by Date, newest first
+
+# Content
+Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization
+that you provide for your content to minimize any extra configuration, though this can be overridden
+by additional configuration in the front matter.
+
+## Organization
+In Hugo the content should be arranged in the same way they are intended for the rendered website.
+Without any additional configuration the following will just work.
+
+ .
+ └── content
+ ├── post
+ | ├── firstpost.md // <- http://site.com/post/firstpost.html
+ | └── secondpost.md // <- http://site.com/post/secondpost.html
+ └── quote
+ ├── first.md // <- http://site.com/quote/first.html
+ └── second.md // <- http://site.com/quote/second.html
+
+
+## Front Matter
+
+The front matter is one of the features that gives Hugo it's strength. It enables
+you to include the meta data of the content right with it. Hugo supports a few
+different formats. The main format supported is JSON. Here is an example:
+
+ {
+ "Title": "spf13-vim 3.0 release and new website",
+ "Description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
+ "Tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
+ "Pubdate": "2012-04-06",
+ "Categories": [ "Development", "VIM" ],
+ "Slug": "spf13-vim-3-0-release-and-new-website"
+ }
+
+### Variables
+There are a few predefined variables that Hugo is aware of and utilizes. The user can also create
+any variable they want to. These will be placed into the `.Params` variable available to the templates.
+
+#### Required
+
+**Title** The title for the content.
+**Description** The description for the content.
+**Pubdate** The date the content will be sorted by.
+**Indexes** These will use the field name of the plural form of the index (see tags and categories above)
+
+#### Optional
+
+**Draft** If true the content will not be rendered unless `hugo` is called with -d
+**Type** The type of the content (will be derived from the directory automatically if unset).
+**Slug** The token to appear in the tail of the url.
+ *or*
+**Url** The full path to the content from the web root.
+*If neither is present the filename will be used.*
+
+## Example
+Somethings are better shown than explained. The following is a very basic example of a content file:
+
+**mysite/project/nitro.md <- http://mysite.com/project/nitro.html**
+
+ {
+ "Title": "Nitro : A quick and simple profiler for golang",
+ "Description": "",
+ "Keywords": [ "Development", "golang", "profiling" ],
+ "Tags": [ "Development", "golang", "profiling" ],
+ "Pubdate": "2013-06-19",
+ "Topics": [ "Development", "GoLang" ],
+ "Slug": "nitro",
+ "project_url": "http://github.com/spf13/nitro"
+ }
+
+ # Nitro
+
+ Quick and easy performance analyzer library for golang.
+
+ ## Overview
+
+ Nitro is a quick and easy performance analyzer library for golang.
+ It is useful for comparing A/B against different drafts of functions
+ or different functions.
+
+ ## Implementing Nitro
+
+ Using Nitro is simple. First use go get to install the latest version
+ of the library.
+
+ $ go get github.com/spf13/nitro
+
+ Next include nitro in your application.
+
+
+
+# Extras
+
+## Shortcodes
+Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that
+markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it.
+
+However we cannot accept being constrained by our simple format. Also unacceptable is writing raw
+html in our markdown every time we want to include unsupported content such as a video. To do
+so is in complete opposition to the intent of using a bare bones format for our content and
+utilizing templates to apply styling for display.
+
+To avoid both of these limitations Hugo has full support for shortcodes.
+
+### What is a shortcode?
+A shortcode is a simple snippet inside a markdown file that Hugo will render using a template.
+
+Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively.
+Short codes are space delimited. The first word is always the name of the shortcode. Following the
+name are the parameters. The author of the shortcode can choose if the short code
+will use positional parameters or named parameters (but not both). A good rule of thumb is that if a
+short code has a single required value in the case of the youtube example below then positional
+works very well. For more complex layouts with optional parameters named parameters work best.
+
+The format for named parameters models that of html with the format name="value"
+
+### Example: youtube
+
+ {{% youtube 09jf3ow9jfw %}}
+
+This would be rendered as
+
+
+
+
+
+
+### Creating a shortcode
+
+All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory.
+
+The template name will be the name of the shortcode.
+
+**Inside the template**
+
+To access a parameter by either position or name the index method can be used.
+
+ {{ index .Params 0 }}
+ or
+ {{ index .Params "class" }}
+
+To check if a parameter has been provided use the isset method provided by Hugo.
+
+ {{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }}
+
+
+# Meta
+
+## Release Notes
+
+* **0.7.0** July 4, 2013
+ * Hugo now includes a simple server
+ * First public release
+* **0.6.0** July 2, 2013
+ * Hugo includes an example documentation site which it builds
+* **0.5.0** June 25, 2013
+ * Hugo is quite usable and able to build spf13.com
+
+## Roadmap
+In no particular order, here is what I'm working on:
+
+ * Pagination
+ * Support for top level pages (other than homepage)
+ * Series support
+ * Syntax highlighting
+ * Previous & Next
+ * Related Posts
+ * Support for TOML front matter
+ * Proper YAML support for front matter
+ * Support for other formats
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Contributors
+
+* [spf13](https://github.com/spf13)
+
+
+## License
+
+Hugo is released under the Simple Public License. See [LICENSE.md](https://github.com/spf13/hugo/blob/master/LICENSE.md).
+