Clean up README and sample-config

2 files changed, 223 insertions, 195 deletions

diff --git a/README.md b/README.md
index 8200d0e..38fe7e0 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 # Hugo-Octopress
-Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hugo][hugo-link]. For a live demo of the website please see my website at [https://parsiya.net](https://parsiya.net).
+Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hugo][hugo-link]. For a live demo please see my personal website at [https://parsiya.net](https://parsiya.net).
 
 ## Contents
 - [Config file parameters](#config)
@@ -21,6 +21,7 @@ Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hu
 - [Table of contents](#tableofcontents)
 - [Not Found or 404.html](#notfound)
 - [Taxonomy pages](#taxonomy)
+- [Disqus](#disqus)
 - [Issues/TODO](#issues)
 - [Attribution](#attribution)
 - [Ported by](#portedby)
@@ -29,7 +30,7 @@ Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hu
 ![screenshot](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/screenshot.png)
 
 ## <a name="config"></a>Configuration
-This section is about parameters in the [configuration file](https://gohugo.io/overview/configuration/) and how they can be used to customize the output. A working config file `sample-config.toml` is provided and miscellaneous parameters are explained below:
+Hugo-Octopress can be configured by modifying the parameters in the [configuration file](https://gohugo.io/overview/configuration/). A working config file `sample-config.toml` is provided. Some miscellaneous parameters are explained below:
 
 ``` toml
 baseurl = "http://example.com"
@@ -38,11 +39,12 @@ languageCode = "en-us"
 title = "Site title"
 theme = "hugo-octopress"
 
-# Number of blog posts displayed in each page
+# Number of blog posts in each pagination page
 paginate = 6
 
 [permalinks]
-post = "/blog/:year-:month-:day-:title/" # change the post URL to look like the old ones
+# Configures post URLs
+post = "/blog/:year-:month-:day-:title/"
 
 # Make tags and categories work
 [indexes]
@@ -51,69 +53,78 @@ post = "/blog/:year-:month-:day-:title/" # change the post URL to look like the
 
 [params]
 
-	# If false, all of the post will appear on front page (and in pagination)
+	# If false, all of blog post will appear on front page (and in pagination)
 	truncate = true
 
-	# Author's name (this will appear in metadata and under posts)
+	# Author's name (appears in meta tags and under posts)
 	author = "Author's name"
 
-	# This text appears in the site header under website title
+	# This text appears in site header under website title
 	subtitle = "Subtitle appears under website title"
 
-	# Used in the search engine
+	# Search engine URL
 	searchEngineURL = "https://www.google.com/search"
 
-	# Text of the "Continue Reading" label. &rarr; == right arrow, but it gets messed up in the string so we will add it to index.html manually
+	# Text of the "Continue Reading" label. &rarr; == right arrow, but it gets messed up in the string so it was added to index.html manually
 	continueReadingText = "Would you like to know more?"
 
-	# Google analytics code
-	googleAnalytics = "google analytics"
+	# Google analytics code - remove if you do not have/want Google Analytics - needs JavaScript
+	googleAnalytics = "UA-XXXXX-X"
 
 	# Disqus shortcode
-	# Disable comments for a specific post by adding "comments: false" in its frontmatter
+	# Disable comments for any individual post by adding "comments: false" in its frontmatter
 	disqusShortname = "Your disqus shortname"
 
-	rss = true  # switch to true to enable RSS icon link
+  # Switch to true to enable RSS icon link
+	rss = true
 
   # Set to true to use a text label for RSS instead of an icon
-  # This is overwritten by the `rss` setting
+  # This is overwritten by the "rss" setting
   textrss = false
 
 	# Website's default description
 	defaultDescription = ""
 
-	# Populate this with your own search keywords - these will appear in the meta tags
+	# Populate this with your own search keywords - these will appear in meta tags
 	# defaultKeywords = ["keyword1" , "keyword2" , "keyword3" , "keyword4"]
+
+  # Set to true to hide ReadingTime on posts
+  disableReadingTime = false
+
+  # Set to true to disable downloading of remote Google fonts
+  disableGoogleFonts = false
 ```
 
 ## <a name="highlight"></a>Code highlight
-Octopress classic theme uses the pygments' `solarized dark` theme. It is not installed by default. It should be installed from https://github.com/john2x/solarized-pygment.git. Then there are three options:
+Octopress classic theme uses the pygments' `solarized dark` for highlighting. It is not installed by default. You can get it from https://github.com/john2x/solarized-pygment. It has three options:
 
-* solarized_light: default
-* solarized_dark: the default one
+* solarized_light: default option after installation
+* solarized_dark: use this to re-create the Octopress classic theme highlighting
 * solarized_dark256
 
-The following options in `config.toml` modify the behavior:
+The following options control code highlighting:
 
 ``` toml
 [params]
-  # Keep it as false please, the css file contains the code for highlighting
+  # Keep it as false please, the CSS file contains the code for highlighting
   pygmentsuseclasses = false
 
   # If nothing is set, then solarized_light is used
-  # Other styles can be viewed in [http://pygments.org/](http://pygments.org/)
   pygmentsstyle = "solarized_dark"
 
   # Highlight shortcode and code fences (```) will be treated similarly
   pygmentscodefences = true
 
-  # pygments options can be added here
+  # pygments options can be added here (and in the highlight shortcode in the markdown file)
   # Hugo supports these pygments options: style, encoding, noclasses, hl_lines, linenos
   # for example: pygmentsoptions = "linenos=true"
 ```
+
+For more information see [Syntax Highlighting](https://gohugo.io/extras/highlighting/) in Hugo's documentation.
+
 ## <a name="markdown"></a>Markdown options
 
-Blackfriday is Hugo's markdown engine. For a list of options visit [https://gohugo.io/overview/configuration/](https://gohugo.io/overview/configuration/) (scroll down to `Configure Blackfriday rendering`). Blackfriday options can be set in the `config.toml` file as follows:
+Blackfriday is Hugo's markdown engine. For a list of options see [Configure Blackfriday rendering](https://gohugo.io/overview/configuration/#configure-blackfriday-rendering). Blackfriday options can be set as follows:
 
 ``` toml
 [blackfriday]
@@ -122,9 +133,9 @@ Blackfriday is Hugo's markdown engine. For a list of options visit [https://gohu
 ```
 
 ## <a name="cssoverride"></a>CSS override
-You can override the built-in css by using your own. Just put your own css files in the `static` directory of your website (the one in the theme directory also works but is not recommended) and modify the `customCSS` parameter in your config file. The path referenced in the parameter should be relative to the `static` folder. These css files will be added through the `header` partial after the built-in css file.
+You can override the built-in CSS and use your own. Just put your own CSS files in the `static` directory of your website (the one in the theme directory also works but is not recommended for obvious reasons) and modify the `customCSS` parameter. The path should be relative to the `static` folder. These CSS files will be added through the `header` partial after the built-in CSS file.
 
-For example, if your css files are `static/css/custom.css` and `static/css/custom2.css` then add the following to the config file:
+For example, if your custom CSS files are `static/css/custom.css` and `static/css/custom2.css` then `customCSS` will look like this:
 
 ``` toml
 [params]
@@ -132,11 +143,11 @@ For example, if your css files are `static/css/custom.css` and `static/css/custo
 ```
 
 ## <a name="menu"></a>Navigation menu
-Links to the left of the navigation menu (everything other than Google search and RSS icon) can be configured here. Navigation menu is generated using the `hugo-octopress/layouts/partials/navigation.html` template.
+Links in the navigation menu (everything other than Google search and RSS icon) can be configured here. Navigation menu is generated using the `layouts/partials/navigation.html` template.
 
-By default navigation menu links will open in the same window. You can change this by setting the `navigationNewWindow` parameter in the config file as seen below. Links to root ("/") will always open in the same window. Currently Hugo does not support adding custom attributes to menu items.
+By default navigation menu links will open in the same window. You can change this behavior by setting the `navigationNewWindow` parameter to true. Links to root ("/") will always open in the same window. Currently Hugo does not support adding custom attributes to menus.
 
-Links are sorted according to weight from left to right. For example a link with weight of `-10` will be to the left of links with weight `0` or `10`. Links can be added to the `config.toml` as follows:
+Links are sorted according to weight from left to right. For example a link with weight of `-10` will be to the left of links with weights `0` or `10`. Links can be added to the config file like this:
 
 ``` toml
 [[menu.main]]
@@ -155,38 +166,50 @@ Links are sorted according to weight from left to right. For example a link with
 
 [params]
   # If set to true, navigation menu links will open in a new window with the exception of links to root ("/")
-  # If this item does not exist or set to false, then navigation menu links will open in the same window
+  # If this item does not exist or is set to false, then navigation menu links will open in the same window
 	navigationNewWindow = true
 ```
 
-The search engine can also be customized in the `config.toml` file as follows:
+Search engine can also be customized:
 
 ``` toml
 [params]
-  # Search engine parameter in the navigation menu
   searchEngineURL = "https://www.google.com/search"
 ```
 
 ## <a name="sidebarlinks"></a>Sidebar
-Sidebar has four parts from top to bottom:
+Sidebar has four parts. From top to bottom it has:
 
 * Sidebar header and text (optional).
-* Social network icons (optional): These are links to Github, Bitbucket, etc accompanied by icons.
-* Sidebar menu (optional): Optional links (usually used for categories).
-* Recent posts: Displays last X (default is 5) published posts.
+* Social network icons (optional): Icons and links to Github, Bitbucket and more.
+* Sidebar menu (optional): Links in sidebar (I use them for internal category pages but you can have external links).
+* Recent posts: Displays last X (default is 5) posts.
 
-The sidebar is generated using the partial template at `hugo-octopress/layouts/partials/sidebar.html`.
+The sidebar is generated using the partial template at `layouts/partials/sidebar.html`.
 
 ### <a name="sidebartext"></a>Sidebar text
-Sidebar text has two parts and both can be configured in the config file. Both values are passed to `markdownify`. For example you can add links and new lines.
+Sidebar text has two parts and both can be configured. Both values are passed to `markdownify` so you can use markdown (e.g. add links or new lines).
 
-* Sidebar header which appear on top in a `<h1>` tag. Can be configured in the config file through the `sidebarHeader` tag.
-* Sidebar text appears under the header and can be configured by modifying the `sidebarText` tag in the config file.
+* Sidebar header appears first in an `<h1>` tag. It can be configured through the `sidebarHeader` parameter.
+* Sidebar text appears under the header and can be configured by modifying `sidebarText`.
 
-New lines can be added with `</br>` or normal markdown (two spaces at the end of line or two new lines). When adding two new lines, remember to remove the indentation in the config file otherwise the new line will be treated as a codeblock
+New lines can be added with `</br>` or in markdown format (two spaces at the end of line or one empty line in between). When adding two new lines, remember to remove the indentation at the start of the new line otherwise the it will be treated as a codeblock.
+
+``` toml
+sidebarHeader = "Sidebar Header"
+
+sidebarText = """Here's a [link to google](https://www.google.com)
+</br>
+Second line
+</br>
+Third line
+This line has two spaces in the end to create a new line using markdown  
+Forth line
+"""
+```
 
 ### <a name="sidebarsocial"></a>Social network icons
-Sidebar links are read from the config file as follows:
+Sidebar social network icons are configured as follows:
 
 ``` toml
 [params]
@@ -200,17 +223,20 @@ Sidebar links are read from the config file as follows:
   googleplus = ""
   youtube = ""
   facebook = ""
+  instagram = ""
 ```
 
-If more than links are added, then add a `</br>` between the first four and the rest. Code to display links (and the idea to use these icons) was taken from [Hyde-x](https://github.com/zyro/hyde-x/).
+Icon sequence can be configured in `layouts/partials/sidebar.html` (look for `<li class="sidebar-nav-item">`). Add a `</br>` tag to create a new line.
+
+Code to display links (and the idea to use these icons) is from [Hyde-x](https://github.com/zyro/hyde-x/).
 
-Icons are from [http://fontawesome.io](http://fontawesome.io) by Dave Gandy. To use icons with square dark backgrounds add `-square`. For example `<i class="fa fa-twitter-square fa-3x"></i>`. Size can be from 1 to 5 or `fa-lg` to be adaptive.
+Icons are from [http://fontawesome.io](http://fontawesome.io) by Dave Gandy. To use icons with square dark backgrounds add `-square`. For example `<i class="fa fa-twitter-square fa-3x"></i>`. Size can be from 1 to 5 use `fa-lg` to make them adaptive.
 
 ### <a name="sidebarmenu"></a>Sidebar menu
-This menu can be enabled by setting the `sidebarMenuEnabled` to `true` in config file. It has two main parts:
+This menu can be enabled by setting `sidebarMenuEnabled` to `true`. It has two parts:
 
-* A header that appears inside the `<h1>` at the top. It can be set in the config file using the `sidebarMenuHeader`. This part only supports text.
-* A series of links. They can be set in the config file similar to navigation menus using the `[[menu.sidebar]]` tag as follows:
+* A header that appears inside the `<h1>` tag on top. It can be set by `sidebarMenuHeader`. This part only supports text.
+* A series of links. They can be configured similar to navigation menu items by using the `[[menu.sidebar]]` tag:
 
         [[menu.sidebar]]
           Name = "Google"
@@ -222,18 +248,18 @@ This menu can be enabled by setting the `sidebarMenuEnabled` to `true` in config
           URL = "/categories/hugo/"
           weight = 1
 
-  * If the `sidebarNewWindow` parameter in config file to `true` to open the sidebar links in a new window. If this parameter does not exist or set to `false` then links open in the same window (default behavior).
+  * Set `sidebarNewWindow` to `true` to open these links in a new window.
 
 ### <a name="sidebarrecent"></a>Recent posts
-Last x recent posts can be displayed in the sidebar. This number can be set in the config file using the `sidebarRecentLimit`. To hide this section either remove `sidebarRecentLimit` from the config file or set it to zero.
+Last x posts can be displayed in the sidebar. This number is controlled by `sidebarRecentLimit`. To hide this section either remove `sidebarRecentLimit` or set it to zero.
 
 ## <a name="shortcodes"></a>Shortcodes
-Creating [shortcodes](https://gohugo.io/extras/shortcodes/) in Hugo was surprisingly easy. I used two plugins in Octopress that I re-created in Hugo using shortcodes. They add captions to code blocks and images. These shortcodes are located at `hugo-octopress/layouts/shortcodes/`.
+Creating [shortcodes](https://gohugo.io/extras/shortcodes/) in Hugo was surprisingly easy (and one of the reasons I switched to it). I used two plugins in Octopress that I re-created in Hugo using shortcodes. They add captions to code blocks and images. These shortcodes are located at `layouts/shortcodes/`.
 
 I have created a repository for all of my Hugo shortcodes at [https://github.com/parsiya/Hugo-Shortcodes](https://github.com/parsiya/Hugo-Shortcodes).
 
 ### <a name="codecaption"></a>Code caption
-This shortcode adds a caption to codeblocks. The codeblock is wrapped in a `<figure>` tag and caption is added using `<figcaption>`. It has two parameters, `title` which is the caption of the code block and `lang` which is the language that is passed to the Hugo `highlight` function along with `linenos=true` which adds line numbers to the codeblock.
+This shortcode adds a caption to codeblocks. The codeblock is wrapped in a `<figure>` tag and caption is added using `<figcaption>`. It has two parameters, `title` which is the caption of the code block and `lang` which is the language that is passed to the Hugo's `highlight` function along with `linenos=true` to enable line numbers.
 
 Shortcode usage (and source) is as follows (please note that parameters are named and not positional):
 
@@ -250,11 +276,11 @@ Shortcode usage (and source) is as follows (please note that parameters are name
 {{< /codecaption >}}
 ```
 
-And will look like this:
+And will look like:
 
 ![picture](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/codecaption1.png).
 
-If the code inside the tag overflows, a horizontal sidebar will be added to the table. It took me a while to achieve this as the `highlight` function created tables that were out of my control. The output from `highlight` is wrapped in `<div class="codewrapper">` and the scroll bar will be added for the whole `div`. The following in the `css` (starting from line 2225) enables this behavior:
+If the code inside the tag overflows, a horizontal sidebar will be added to the table. It took me a while to achieve this as the `highlight` function created tables that were out of my control. The output from `highlight` is wrapped in `<div class="codewrapper">` and the scroll bar will be added for the whole `div`. The following in the CSS file (starting from line 2225) enables this behavior:
 
 ``` css
 div.codewrapper {
@@ -265,7 +291,7 @@ div.codewrapper {
 ```
 
 ### <a name="imgcap"></a>Image caption
-This shortcode adds captions to pictures. Due to the way the original `css` file was organized, this shortcode does not use `<figure>` and `<figcaption>`. `Alt` will also be set to `title`.
+This shortcode adds captions to pictures. Due to the way the original CSS file was organized, this shortcode does not use `<figure>` and `<figcaption>`. `Alt` tag is also set to `title`.
 
 Usage is as follows (please note that parameters are named and not positional):
 
@@ -282,9 +308,9 @@ Will result in:
 </span>
 ```
 #### <a name="snippets"></a>Atom snippets for shortcodes
-I use Atom editor these days so I created a couple of snippets to insert these shortcodes while editing Markdown files. In order to read on how to create snippets please refer to [Atom's Snippets package](https://github.com/atom/snippets).
+In order to read about creating Atom snippets please see [Atom's Snippets package](https://github.com/atom/snippets).
 
-Open your snippets file (on Windows it's `File > Open Your Snippets`) and paste the following in the file:
+Open your snippets file (`File > Open Your Snippets`) and paste the following:
 
 ``` coffee
 '.source.gfm':
@@ -302,30 +328,31 @@ Open your snippets file (on Windows it's `File > Open Your Snippets`) and paste
 
 My original mistake was to repeat `'.source.gfm'` before the `imgcap` snippet, seems like [cson keys should not be repeated](https://atom.io/docs/latest/using-atom-basic-customization#id-D9ATX).
 
-You can trigger the shortcodes by entering `imgcap` and `codecap` respectively and then pressing enter. You can change these by modifying the `prefix` in the code above. After inserting the shortcode, the cursor will go to the first location which is designated by `$1` which is `title` in both cases. After entering the value you can go to `$2` and `$3` by pressing `tab`.
-
-Hopefully these snippets help in using these shortcodes.
+You can trigger the shortcodes by entering `imgcap` and `codecap` respectively and then pressing enter. You can change these keywords by modifying the `prefix` tag. After inserting the shortcode, the cursor will go to the first location which is designated by `$1`. After entering the first parameter you can go to `$2` and then `$3` using `tab`.
 
 ## <a name="summary"></a>Hugo page summary bug
-If no page summary is selected, Hugo will take the first 70 words of your post (stripped on HTML tags) and displays them. This is ugly. Instead use the summary divider `<!--more-->` to specify where the summary ends. Hugo currently has a problem that reference style links in summary are not displayed. The reason behind this problem is that Hugo take the everything before the summary divider and passes it to the Markdown engine (currently BlackFriday) and if your reference style links are at the bottom of the page (they usually are), they are not passed. You can read more about this bug [here](https://discuss.gohugo.io/t/markdown-content-renders-as-regular-text-in-summary/1396/12).
+If no page summary is designated in the post, Hugo will use first 70 words (HTML tags are stripped). The result is usually ugly. Instead use the summary divider `<!--more-->` to specify where the summary ends in post source.
+
+Hugo currently does not display reference style links in post summary. Because it takes everything before the summary divider and passes it to the Markdown engine (currently BlackFriday) and if your reference style links are at the bottom of the page (they usually are), they are not included. As a result your reference style links will be treated as unformatted text. You can read more about this bug [here](https://discuss.gohugo.io/t/markdown-content-renders-as-regular-text-in-summary/1396/12).
 
-To be more specific, reference style links are like this:
+To be more specific, reference style links look like this:
 
 ``` markdown
 This is a link to [Google][google-link].
 
-More stuff here
+More stuff here.
 
+Usually at the end of the markdown file.
 [google-link]: https://www.google.com
 ```
 
-Currently you can avoid this bug in two ways:
+There are two workarounds:
 
-1. Do not use reference style links in summary. Use normal links like this `[Google](https://www.google.com)`.
-2. Put the reference link before the summary divider.
+1. Do not use reference style links in summary. Use normal links like `[Google](https://www.google.com)`.
+2. Put the reference links before the summary divider.
 
 ## <a name="licensepage"></a>License page
-The generated license page will be located at `example.com/license/`. Markdown code for the license page can be anywhere in the content page, however the type of the markdown file should be set to `license` in front material. For example:
+License page will be located at `baseurl/license/`. Markdown code for the license page can be anywhere in the content directory, however the type of the markdown file should be set to `license` in frontmatter. For example:
 
     ---
     title: "License"
@@ -334,14 +361,14 @@ The generated license page will be located at `example.com/license/`. Markdown c
 
     License text
 
-License page template is located at: `hugo-octopress\layouts\license\single.html`.
+License page template is located at: `layouts/license/single.html`.
 
 ## <a name="tableofcontents"></a>Table of contents
-The theme supports adding `Table of Contents (ToC)` to pages. This is added in `hugo-octopress\layouts\post\single.html`. The ToC does not appear in the summary but is on top of the actual page. Currently ToC is only accessible in the templates and there is no way to access it inside the page using shortcodes. This is due to limitations in BlackFriday (Hugo's markdown engine).
+The theme supports adding `Table of Contents (ToC)` to pages. This is done in `layouts/post/single.html`. The ToC does not appear in the summary but is on top of the actual page. Currently ToC is only accessible in the templates and there is no way to access it inside the page using shortcodes. This is a limitation of BlackFriday (Hugo's markdown engine).
 
-There are two ways to enable Table of Contents:
+There two ways to enable the ToC:
 
-* Each post/page can have a variable named `toc` in its frontmatter. This needs to be set to `true`.
+1. Each post/page can have a variable named `toc` in its frontmatter. This needs to be set to `true`.
 
 ```
 title: "title"
@@ -350,45 +377,42 @@ draft: false
 toc: true
 ```
 
-* Global setting is available in the config file, `tableOfContents` under `[Params]` need to be set to `true`.
+2. Global setting is available in the config file, `tableOfContents` under `[Params]` needs to be set to `true`.
 
 ```
 [Params]
   tableOfContents = true
 ```
 
-The `toc` variable in frontmatter has priority. If it is set `false` then the config file is ignored. It is recommended to not set use the config file and enable the ToC for individual pages. Otherwise, it can be enabled for all pages in the config file and disabled for specific pages using the frontmatter.
+The `toc` variable in frontmatter has priority. If it is set to `false` then `tableOfContents` in the config file is ignored. Depending on your usage, you can not use it in the config file and set it for individual pages. Otherwise, it can be enabled for all pages and disabled for specific pages in the frontmatter.
 
 ## <a name="notfound"></a>Not Found or 404.html
-You can customize the `404.html` page in the config menu. For extensive customization you can modify the template at `hugo-octopress\layouts\404.html`.
-
-There are two optional parameters in the config file and both support markdown:
+The `404.html` has two optional parameters and both support markdown:
 
 * notFoundHeader: 404 page title
 * notFoundText: 404 page text
 
 If they are not set in the config file, a default page is generated.
 
+For extensive customization you can modify the template at `layouts/404.html`
+
 ## <a name="taxonomy"></a>Taxonomy pages
-The theme can create pages that list all taxonomies (categories and tags) and their count. The taxonomy pages are at `baseURL/tags/` and `baseURL/categories`. This can be accomplished by adding `generateTaxonomyList = true` to the config file. By default the theme sorts the items by count. It can be changed to alphabetical by including `sortTaxonomyAlphabetical = true`.
+The theme can create pages that list all taxonomies (categories and tags) and their count. The taxonomy pages are at `baseURL/tags/` and `baseURL/categories`. They will be generated by `generateTaxonomyList = true`. By default items are sorted by count. `sortTaxonomyAlphabetical = true` changes the sort to alphabetical.
 
-The switches are as follows:
+For example:
 
     [Params]
       generateTaxonomyList = true
 
-      # This is not needed unless alphabetical sort is needed
+      # Alphabetical sort
       # sortTaxonomyAlphabetical = true
 
 To revert back to ByCount sort, remove `sortTaxonomyAlphabetical` or set it to false.
 
 ## <a name="issues"></a>Issues/TODO
+If you discover any issues/bugs or want new features please use the Github issue tracker. Please keep in my mind that development has not been my day job for quite a while and I may be slow in fixing things (don't be surprised if I ask you about details).
 
-If you see any issues/bugs or you are looking for some features please use the Github issue tracker. Please keep in my mind that my day job is not development and I may be slow in fixing things (or I may ask you to help me with it).
-
-**The css is a mess.** The `css` file is `screen.css` taken from the classic Octopress theme. I found it easier to just modify the templates to generate HTML code similar to Octopress' output and use the existing `css` file. It's bulky (around 53KBs and 2300 lines) and it probably has code for elements that are never used (also duplicates). It also contains the highlight code (part of the reason it is big).
-
-If you know how to clean it up, please let me know or better yet help me do it :)
+**The css is a mess.** The CSS file is `screen.css` taken directly from the classic Octopress theme. I found it easier to just modify the templates to generate HTML code similar to Octopress' output and use the existing CSS file. It's bulky (around 53KBs and 2300 lines) and it probably has code for elements that are never used (also duplicates). It also contains the highlight code (contributes to size).
 
 ## <a name="attribution"></a>Attribution
 * [Octopress](octopress-link) is created by [Brandon Mathis](https://github.com/imathis). Octopress source can be found on [https://github.com/imathis/octopress](https://github.com/imathis/octopress).
@@ -404,6 +428,6 @@ Ported by Parsia Hakimian:
 ## <a name="themelicense"></a>Theme license
 Open sourced under the [MIT license](https://github.com/parsiya/Hugo-Octopress/blob/master/LICENSE.md).
 
-
+<!-- Links -->
 [octopress-link]: http://octopress.org
 [hugo-link]: https://gohugo.io
diff --git a/sample-config.toml b/sample-config.toml
index a46d665..42e738a 100644
--- a/sample-config.toml
+++ b/sample-config.toml
@@ -4,165 +4,169 @@ languageCode = "en-us"
 title = "Site title"
 theme = "hugo-octopress"
 
-# Number of blog posts displayed in each page
+# Number of blog posts in each pagination page
 paginate = 6
 
+# Keep it as false please, the CSS file contains the code for highlighting
 pygmentsuseclasses = false
 pygmentsstyle = "solarized_dark"
 
-# You need to install Solarized from https://github.com/john2x/solarized-pygment.git
-# Octopress blog used Solarized_dark
-# Options are solarized_dark (octopress), solarized_dark256 and default (solarized light)
+# You need to install Solarized from https://github.com/john2x/solarized-pygment
+# Octopress classic theme uses Solarized_dark
+# Options are solarized_dark (octopress), solarized_dark256 and solarized_light
 
-# This will make the highlight shortcode and ``` do the same thing - otherwise they are treated differently and we do not want that
+# Highlight shortcode and code fences (```) will be treated similarly
 pygmentscodefences = true
 
-# We can pass in pygments options here, it can also be added in the highlight shortcode
-# pygmentsoptions = "linenos=true"
+# pygments options can be added here (and in the highlight shortcode in the markdown file)
+# Hugo supports these pygments options: style, encoding, noclasses, hl_lines, linenos
+# for example: pygmentsoptions = "linenos=true"
 
 [permalinks]
 post = "/blog/:year-:month-:day-:title/" # change the post URL to look like the old ones
 
 # Make tags and categories work
 [indexes]
-	tag = "tags"
-	category = "categories"
+  tag = "tags"
+  category = "categories"
 
-# Menu
-# Links are added to navigation in hugo-octopress/layouts/partials/navigation.html
-# If navigationNewWindow is set in [params] to true then all links except root ("/") will open in a new window
-# If navigationNewWindow does not exist or set to false then links will open in the same window
-[[menu.main]]
-	Name = "Blog"
-	URL = "/"
-	weight = -5
 
-[[menu.main]]
-	Name = "Google"
-	URL = "https://www.google.com/"
-	weight = -5
+[params]
 
-[[menu.main]]
-	Name = "This theme on Github"
-	URL = "https://www.github.com/parsiya/hugo-octopress"
+  # --- Start sidebar options ---
+  # Number of last posts that will be displayed in the sidebar - set to 0 or remove to hide this section
+  sidebarRecentLimit = 5
 
+  # Sidebar header - passed to markdownify so you can write markdown here
+  sidebarHeader = "Sidebar Header"
 
-# Sidebar menus
-# Enable with "sidebarMenuEnabled = true" in [params]
-# Header text is "sidebarMenuHeader" in [params]
-[[menu.sidebar]]
-	Name = "Google"
-	URL = "https://www.google.com"
-	weight = 0
+  # Sidebar text also supports markdown
+  # New lines can be added with </br> or normal markdown (two spaces at the end of line or two new lines).
+  # when adding two new lines, remember to remove the indentation otherwise the new line will be treated as a codeblock
+  sidebarText = """Here's a [link to google](https://www.google.com)
+  </br>
+  Second line
+  </br>
+  Third line
+  This line has two spaces in the end to create a new line using markdown
+  Forth line
+  """
+  # Sidebar menu - if true will add a sidebar menu between sidebar text and recent posts
+  sidebarMenuEnabled = true
+  sidebarMenuHeader = "Sidebar Links"
 
-[[menu.sidebar]]
-	Name = "Hugo"
-	URL = "/categories/hugo/"
-	weight = 1
+  # sidebar links
+  github = "https://github.com/parsiya/"
+  bitbucket = "https://bitbucket.org/parsiya/"
+  twitter = "https://twitter.com/cryptogangsta/"
+  keybase = "https://keybase.io/parsiya/"
+  stackoverflow = ""
+  linkedin = ""
+  googleplus = ""
+  youtube = ""
+  facebook = ""
+  instagram = ""
 
-[[menu.sidebar]]
-	Name = "Homepage"
-	URL = "/"
-	weight = 2
+  # --- End sidebar options ---
 
-[params]
+  # If set to true, navigation menu links will open in a new window with the exception of links to root ("/")
+  # If this item does not exist or set to false, then navigation menu links will open in the same window
+  navigationNewWindow = true
 
-	# --- Start sidebar options ---
-	# Number of recent posts that will be shown in the sidebar - set to 0 or remove to hide this section
-	sidebarRecentLimit = 10
+  # If false, all of blog post will appear on front page (and in pagination)
+  truncate = true
 
-	# Sidebar header - passed to markdownify so you can write markdown here
-	sidebarHeader = "Sidebar Header"
+  # Author's name (appears in meta tags and under posts)
+  author = "Author's name"
 
-	# Sidebar text also sipports markdown
-	# New lines can be added with </br> or normal markdown (two spaces at the end of line or two new lines).
-	# when adding two new lines, remember to remove the indentation otherwise the new line will be treated as a codeblock
-	sidebarText = """Sidebar text is passed to *markdownify* so it supports markdown. Here's a [link to google](https://www.google.com)
-	</br>
-	Second line
-	</br>
-	Third line
-	"""
-	# Sidebar menu - if true will add a sidebar menu between sidebar text and recent posts
-	sidebarMenuEnabled = true
-	sidebarMenuHeader = "Sidebar Links"
+  # This text appears in the site header under website title
+  subtitle = "Subtitle appears under website title"
 
-	# sidebar links
-	github = "https://github.com/parsiya/"
-	bitbucket = "https://bitbucket.org/parsiya/"
-	twitter = "https://twitter.com/cryptogangsta/"
-	keybase = "https://keybase.io/parsiya/"
-	stackoverflow = ""
-	linkedin = ""
-	googleplus = ""
-	youtube = ""
-	facebook = ""
-	instagram = ""
+  # Search engine URL
+  searchEngineURL = "https://www.google.com/search"
 
-	# --- End sidebar options ---
+  # Text of the "Continue Reading" label. &rarr; == right arrow, but it gets messed up in the string so it was added to index.html manually
+  continueReadingText = "Would you like to know more?"
 
-	# If set to true, navigation menu links will open in a new window with the exception of links to root ("\")
-	# If this item does not exist or set to false, then navigation menu links will open in the same window
-	navigationNewWindow = true
+  # Google analytics code - remove if you do not have/want Google Analytics - needs JavaScript
+  # googleAnalytics = "UA-XXXXX-X"
 
-	# If false, all of the post will appear on front page (and in pagination)
-	truncate = true
+  # Disqus shortcode
+  # Disable comments for any individual post by adding "comments: false" in its frontmatter
+  disqusShortname = "Your disqus shortname"
 
-	# Author's name (this will appear in metadata and under posts)
-	author = "Author's name"
+  # Switch to true to enable RSS icon link
+  rss = true
 
-	# This text appears in the site header under website title
-	subtitle = "Subtitle appears under website title"
+  # Set to true to use a text label for RSS instead of an icon
+  # This is overwritten by the "rss" setting
+  textrss = false
 
-	# Used in the search engine
-	searchEngineURL = "https://www.google.com/search"
+  # Website's default description
+  defaultDescription = ""
 
-	# Text of the "Continue Reading" label. &rarr; == right arrow, but it gets messed up in the string so we will add it to index.html manually
-	continueReadingText = "Would you like to know more?"
+  # Populate this with your own search keywords - these will appear in the meta tags
+  # defaultKeywords = ["keyword1" , "keyword2" , "keyword3" , "keyword4"]
 
-	# Google analytics code
-	googleAnalytics = "google analytics"
+  # CSS override files
+  # Paths should be relative to the `static` directory
+  # customCSS = ["css/custom.css","css/custom2.css"]
 
-	# Disqus shortcode
-	# Disable comments for a specific post by adding "comments: false" in its frontmatter
-	disqusShortname = "Your disqus shortname"
+  # 404.html header and text - both support markdown
+  notFoundHeader = "There's nothing here"
 
-	rss = true  # switch to true to enable RSS icon link
+  notFoundText = """Please either go back or use the navigation/sidebar menus.
+  """
 
-	# Set to true to use a text label for RSS instead of an icon
-	# This is overwritten by the `rss` setting
-	textrss = false
+  # Set to true to hide ReadingTime on posts
+  disableReadingTime = false
 
-	# Website's default description
-	defaultDescription = ""
+  # Set to true to disable downloading of remote Google fonts
+  disableGoogleFonts = false
 
-	# Populate this with your own search keywords - these will appear in the meta tags
-	# defaultKeywords = ["keyword1" , "keyword2" , "keyword3" , "keyword4"]
+  # Generate taxonomy pages
+  generateTaxonomyList = true
 
-	# CSS override files
-	# Paths should be relative to the `static` directory (either the website static directory or the theme one)
-	# customCSS = ["css/custom.css","css/custom2.css"]
+  # This is not needed unless alphabetical sort is needed
+  # sortTaxonomyAlphabetical = true
 
-	# 404.html header and text -both support markdown
-	notFoundHeader = "There's nothing here"
+# Menu
+# If navigationNewWindow (under [params]) is set to true then all links except root ("/") will open in a new window
+# If it does not exist or is set to false then links will open in the same window
+[[menu.main]]
+  Name = "Blog"
+  URL = "/"
+  weight = -5
 
-	notFoundText = """Please either go back or use the navigation/sidebar menus.
-	"""
+[[menu.main]]
+  Name = "Google"
+  URL = "https://www.google.com/"
+  weight = -5
 
-	# Set to true to hide ReadingTime on posts
-	disableReadingTime = false
+[[menu.main]]
+  Name = "This theme on Github"
+  URL = "https://www.github.com/parsiya/hugo-octopress"
 
-	# Set to true to disable downloading of remote Google fonts
-	disableGoogleFonts = false
 
-	# Generate taxonomy pages
-	generateTaxonomyList = true
+# Sidebar menus
+# Enable with "sidebarMenuEnabled = true" under [params]
+# Header text is "sidebarMenuHeader" under [params]
+[[menu.sidebar]]
+  Name = "Google"
+  URL = "https://www.google.com"
+  weight = 0
 
-	# This is not needed unless alphabetical sort is needed
-	# sortTaxonomyAlphabetical = true
+[[menu.sidebar]]
+  Name = "Hugo"
+  URL = "/categories/hugo/"
+  weight = 1
 
+[[menu.sidebar]]
+  Name = "Homepage"
+  URL = "/"
+  weight = 2
 
 # Blackfriday is Hugo's markdown engine. Options are at: https://gohugo.io/overview/configuration/ (scroll down to "Configure Blackfriday rendering")
 [blackfriday]
-	hrefTargetBlank = true # open the external links in a new window
-	fractions = false
+  hrefTargetBlank = true # open the external links in a new window
+  fractions = false