added documentation for theme

5 files changed, 164 insertions, 14 deletions

diff --git a/README.md b/README.md
index 9b075e9..7362e2d 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,23 @@
 # internet-weblog Theme for Hugo
 
-internet-weblog is a minimalistic Hugo theme that offers a traditional blog mixed
-with a microblog and a photoblog. It also offers the ability to do simple link
-posts that link to a remote page. It was ported from a theme made for Octopress.
+`internet-weblog` is a minimalistic Hugo theme that offers a traditional blog mixed with a microblog and a photoblog. It also offers the ability to do simple link posts that link to a remote page. It was ported from a theme made for Octopress.
 
-The theme features a customizable bio-section and flickr-based photo stream in
-it's footer, unique layouts for displaying all posts, and other
+The theme features a customizable bio-section and flickr-based photo stream in it's footer, unique layouts for displaying all posts sorted by year, and support for partials to customize style and javascript loaded.
 
-(screenshot)
+![internet-weblog showing a Micropost.](_meta/sample.png)
+
+To see more, [check out my blog which is rendered with this theme](http://jnjosh.com) and see it's [configuration on Github](https://github.com/jnjosh/jnjosh.com).
 
 ## Contents
 
 - [Installation](#installation)
 - [Getting started](#getting-started)
+    - [Configuring Your Blog](#configuring-your-blog)
     - [Variables](#variables)
+    - [Overrides](#overrides)
 - [Contributing](#contributing)
 - [License](#license)
-- [Annotations](#annotations)
+- [Contact](#contact)
 
 ## Installation
 
@@ -24,17 +25,165 @@ Inside the folder of your Hugo site run:
 
     $ mkdir themes
     $ cd themes
-    $ git clone https://github.com/jnjosh/internet-weblog
+    $ git clone https://github.com/jnjosh/internet-weblog.git
 
-For more information read the official [setup guide](//gohugo.io/overview/installing/)
-for Hugo.
+For more information read the official [setup guide](//gohugo.io/overview/installing/) for Hugo.
 
 ## Getting Started
 
-TBA
+There are a few concepts this theme employs to make a personal blog. It's important to read this as you may not see what you expect upon launching. Since this theme is built to be a personal blog it opts for some simplifications like using the ["Section Menu for the Lazy Blogger"](https://gohugo.io/extras/menus/#section-menu-for-the-lazy-blogger) option in Hugo for displaying a simple menu. It assumes you want to call your blog posts `posts` and organizes them as such. For example, creating a new post with Hugo would require you typing:
+
+```
+  $ hugo new posts/my-new-post.md
+```
+
+It also assumes you want to display links to your sections of content (`posts`, `microposts`, `photos`) and display links to other pages in the menu and requires some setup on your part. This guide will take you through the steps to configure your blog to use the theme.
+
+### Configuring your Blog
+
+#### Where should blog post markdown files be stored?
+
+The theme works with other content types, but posts work best when grouped under `posts`. When using the `posts` (_note that it is plural_) content type you'll have a customized list page sorted by year and the default list page. Here's an example:
+
+![Custom List Page sorted by Year](_meta/posts.png)
+
+**Recommendation:** Organize your blog posts under the `posts` directory.
+
+#### How to configure the menu in the blog's navigation
+
+As mentioned above, this theme takes a simplistic approach to menus. In fact, it doesn't really support custom menus opting to just use Hugo's `main` menu. Because it uses the ["Section Menu for the Lazy Blogger"](https://gohugo.io/extras/menus/#section-menu-for-the-lazy-blogger) you'll need to make one change to your `config.toml` file. Add **main** as the `SectionPagesMenu`.
+
+```
+SectionPagesMenu = "main"
+```
+
+Because of this, your individual posts don't need to organize themselves into menu groupings. Everything is assumed to be grouped at the top level. One exception to this is if you want to add a custom page to the root of the menu. In this case you would want to add `menu: main` to your page's Front Matter.
+
+You can control which menu items get an RSS icon and link by adding the `RSSSections` list to your Params section of your `config.toml`:
+
+```
+[params]
+	RSSSections = [ "Posts", "Microposts", "Photos" ]
+```
+
+You can then control the name and weight of these menus in your `config.toml` by adding a section for each menu item you'd like to display:
+
+```
+[[menu.main]]
+  name = "Posts"
+  weight = 1
+	identifier = "posts"
+  url = "/posts/"
+```
+
+If you aren't sure of how this should look, see how [jnjosh.com uses this in it's config.toml](https://github.com/jnjosh/jnjosh.com/blob/master/config.toml).
+
+**Recommendation:** Add `SectionPagesMenu` to your `config.toml` file.  
+**Recommendation:** Don't set a `menu` in your post's Front Matter unless you want it to display on the navigation.  
+**Recommendation:** Customize the menus that get an RSS icon by adding the `RSSSections` parameter to your `config.toml` file.  
+**Recommendation:** Configure the menu items by adding `menu.main` sections to your `config.toml` file.
+
+#### Defining yourself as the Author
+
+It looks like most themes use the `author` variable to add something simple like your name. This theme uses more structured data about you and requires an `[author]` section. The details of what is affected by each property is defined below in the variables section, but you should add this section to your `config.toml`:
+
+```
+[author]
+	Handle = "<Your `handle`>"
+	FirstName = "<Your First Name>"
+	LastName = "<Your Last Name>"
+	AboutPage = "<The relative or complete link to your about page>"
+	Location = "<Your Location>"
+	FlickrID = "<Your Flickr ID>"
+```
+
+**Recommendation:** Don't use the `author` variable, use the above `[author]` section in your `config.toml`.
+
+#### Customizing the Bio Section, 404 page, javascript, or stylesheets
+
+There are a few entry points for you to customize built in. The most important one is the `bio.html` partial. The contents of this file are displayed in the left side of the footer. To customize this, add a `bio.html` file in your site's directory under `layouts/partials`.
+
+More details about each of these overrides are below in the [overrides](#overrides) section.
+
+**Recommendation:** Add a `layouts/partials/bio.html` file to your site that tells your readers about you.
 
 ### Variables
 
+| Variable | What value? | Required |
+|---|---|---|
+| `theme`  | `internet-weblog` | Only if you want to use this theme! 😃|
+| `title` | `internet weblog` | No. Unless you want to call your blog something else. |
+| `SectionPagesMenu` | `main` | Yes. See [above](#configuring-your-blog). |
+| `[author]` - `Handle` | A short handle to describe you. This could be your twitter handle or simply your first name. | Yes. This is used to generate the Site's Title. |
+| `[author]` - `FirstName` | Your first name | Yes. This is used in the footer to say Hi and in other places to identify you as the author. |
+| `[author]` - `LastName` | Your last name | Not really. It is used in some places to identify you as the author. |
+| `[author]` - `AboutPage` | `/about` or `http://about.othersite.com` | Only if you want an about page. This is exposed to allow you to link to an external about page as well. If you have a local page it can just be something relative. |
+| `[author]` - `Location` | `Your City` | No. If set, this is added to the Copyright in the footer so you can give some love to your hometown. |
+| `[author]` - `FlickrID` | `Your Flickr ID` | Kind of. The footer shows your photo stream from flickr. If you don't set it you'll see random photos that Flickr serves you. |
+| `[params]` - `Description` | `Describe your site` | No. If set this is added to your pages metadata. |
+| `[params]` - `ShowCopyright` | `true` or `false` | No. If true, Copyright text will be added to the footer. |
+| `[params]` - `RSSEnabled` | `true` or `false` | No. If true, RSS pages will be generated. |
+| `[params]` - `RSSSections` | `[ "Posts", "Microposts", "Photos" ]` | If you want RSS links in the menu, Yes. These strings need to be the display name of the section where you want to have an RSS icon displayed. ![rss](_meta/rss.png) |
+
+Here is an example `config.toml`:
+
+```
+baseurl = "http://mysite.com/"
+languageCode = "en-us"
+title = "internet weblog"
+theme = "internet-weblog"
+Paginate = 10
+SectionPagesMenu = "main"
+
+[author]
+	Handle = "jnjosh"
+	FirstName = "Josh"
+	LastName = "Johnson"
+	AboutPage = "/about"
+	Location = "Durham, NC"
+	FlickrID = "87151163@N00"
+
+[params]
+	Description = "This is my blog, read it and enjoy."
+	ShowCopyright = true
+	RSSEnabled = true
+	RSSSections = [ "Posts", "Microposts", "Photos" ]
+
+[taxonomies]
+	tag = "tags"
+	category = "categories"
+	series = "series"
+
+[[menu.main]]
+  name = "Posts"
+  weight = 1
+	identifier = "posts"
+  url = "/posts/"
+
+[[menu.main]]
+	name = "Microposts"
+	weight = 2
+	identifier = "microposts"
+	url = "/microposts/"
+
+[[menu.main]]
+	name = "Photos"
+	weight = 3
+	identifier = "photos"
+	url = "/photos/"
+```
+
+### Overrides
+
+The theme expects you to override a few files in your blog to finalize the customization of your blog. Below is a list of the files you can override and why you'd want to. To override these, create your own version of the file under `layouts/partials`—you may need to create this directory.
+
+| File  | Why override?  | Required |
+|---|---|---|
+| `bio.html` | The footer of the blog features a section about you. | Yes. Otherwise it just has default text. |
+| `not_found.html` | If you want to customize the 404 not found page, you can update it here. | Probably. The default is pretty plain. |
+| `custom_javascript.html` | If you need all pages to have your own custom javascript files referenced, you can do so here. | No |
+| `custom_stylesheets.html` | If you need all pages to have your own custom stylesheets referenced, you can do so here. | No |
+| `custom_image_handler.html` | The footer of the blog features a photo stream. If you want to customize it or use a different source, you can override this behavior. |  No |
 
 ## Contributing
 
@@ -46,6 +195,8 @@ This theme is released under MIT. For more information, please see the [License]
 
 ## Contact
 
+This is the first theme I've made for Hugo, so I'm sure I've done some things wrong or assumed too much. If you have ideas or things that should be fixed, please let me know.
+
 - [Josh Johnson](http://jnjosh.com) [@jnjosh](http://twitter.com/jnjosh)
 
 ---
diff --git a/_meta/posts.png b/_meta/posts.png
new file mode 100644
index 0000000..87955c1
--- /dev/null
+++ b/_meta/posts.png
diff --git a/_meta/rss.png b/_meta/rss.png
new file mode 100644
index 0000000..b4300a3
--- /dev/null
+++ b/_meta/rss.png
diff --git a/_meta/sample.png b/_meta/sample.png
new file mode 100644
index 0000000..fa7ae6e
--- /dev/null
+++ b/_meta/sample.png
diff --git a/theme.toml b/theme.toml
index ab58847..93a2c80 100644
--- a/theme.toml
+++ b/theme.toml
@@ -3,9 +3,8 @@ license = "MIT"
 licenselink = "https://github.com/jnjosh/internet-weblog/blob/master/LICENSE.md"
 description = "A personal, minimal blog theme for Hugo."
 homepage = "http://jnjosh.com"
-tags = ["blog", "personal", "minimal", "microblog", "photoblog", "linkblog"]
-features = ["Microblog", "Photoblog", "Blog", "Flickr Photo Stream", "Personal Blog", "Link Blog"]
-version = 1.0
+tags = ["blog", "personal", "minimal", "microblog", "photoblog", "linkblog", "responsive"]
+features = ["Microblog", "Photoblog", "Blog", "Flickr Photo Stream", "Personal Blog", "Link Blog", "Responsive"]
 min_version = 0.14
 
 [author]