[Docs] More random revision and copyediting

General revisions to (hopefully) make the documentation
easier to understand and more comprehensive.

Revise "Strange EOF error" troubleshooting page to say that
a fix is in place for the upcoming Hugo v0.13.

Also add more external links, and cute icons from Font Awesome.

docs/content/content/archetypes.md

@@ -10,51 +10,62 @@ weight: 50
 ---
 
 Hugo v0.11 introduced the concept of a content builder. Using the
-command: `hugo new [relative new content path]` you can start a content file
+command: <code>hugo new <em>[relative new content path]</em></code>,
-with the date and title automatically set. This is a welcome feature, but 
+you can start a content file with the date and title automatically set.
-active writers need more. 
+While this is a welcome feature, active writers need more.
 
-Hugo presents the concept of archetypes which are archetypal content files.
+Hugo presents the concept of archetypes, which are archetypal content files
+with pre-configured [front matter](content/front-matter) which will
+populate each new content file whenever you run the `hugo new` command.
 
-## Example archetype
 
-In this example scenario I have a blog with a single content type (blog post).
+## Example
-I use ‘tags’ and ‘categories’ for my taxonomies.
 
-### archetypes/default.md
+### Step 1. Creating an archetype
+
+In this example scenario, we have a blog with a single content type (blog post).
+We will use ‘tags’ and ‘categories’ for our taxonomies, so let's create an archetype file with ‘tags’ and ‘categories’ pre-defined, as follows:
+
+#### archetypes/default.md
 
     +++
     tags = ["x", "y"]
     categories = ["x", "y"]
     +++
 
-__NOTE:__  Some editors (e.g. Sublime) do not insert an EOL at the last line.  If you get an EOF error using `hugo new` type a carriage return `<Enter>` after the closing `+++` in each archetype file.
+__CAVEAT:__  Some editors (e.g. Sublime, Emacs) do not insert an EOL (end-of-line) character at the end of the file (i.e. EOF).  If you get a [strange EOF error](/troubleshooting/strange-eof-error/) when using `hugo new`, please open each archetype file (i.e. `archetypes/*.md`) and press <kbd>Enter</kbd> to type a carriage return after the closing `+++` or `---` as necessary.
 
-## Using archetypes
 
-If I wanted to create a new post in the `post` section, I would run the following command:
+### Step 2. Using the archetype
 
-`hugo new post/my-new-post.md`
+Now, with `archetypes/default.md` in place, let's create a new post in the `post` section with the `hugo new` command:
+
+    $ hugo new post/my-new-post.md
 
 Hugo would create the file with the following contents:
 
-### content/post/my-new-post.md
+#### content/post/my-new-post.md
 
     +++
     title = "my new post"
-    date = 2014-05-14T02:13:50Z
+    date = "2015-01-12T19:20:04-07:00"
     tags = ["x", "y"]
     categories = ["x", "y"]
     +++
 
+We see that the `title` and `date` variables have been added, in addition to the `tags` and `categories` variables which were carried over from `archetype/default.md`.
+
+Congratulations!  We have successfully created an archetype and used it for our new contents.  That's all there is to it!
+
 
 ## Using a different front matter format
 
 By default, the front matter will be created in the TOML format
 regardless of what format the archetype is using.
 
-You can specify a different default format in your config file using
+You can specify a different default format in your site-wide config file
-the `MetaDataFormat` directive. Possible values are `toml`, `yaml` and `json`.
+(e.g. `config.toml`) using the `MetaDataFormat` directive.
+Possible values are `"toml"`, `"yaml"` and `"json"`.
 
 
 ## Which archetype is being used
@@ -63,13 +74,13 @@ The following rules apply:
 
 * If an archetype with a filename that matches the content type being created, it will be used.
 * If no match is found, `archetypes/default.md` will be used.
-* If neither are present and a theme is in use, then within the theme:
+* If neither is present and a theme is in use, then within the theme:
     * If an archetype with a filename that matches the content type being created, it will be used.
     * If no match is found, `archetypes/default.md` will be used.
 * If no archetype files are present, then the one that ships with Hugo will be used.
 
-Hugo provides a simple archetype which sets the title (based on the
+Hugo provides a simple archetype which sets the `title` (based on the
-file name) and the date based on `now()`.
+file name) and the `date` based on `now()`.
 
 Content type is automatically detected based on the path. You are welcome to declare which 
 type to create using the `--kind` flag during creation.

docs/content/content/example.md

@@ -13,37 +13,79 @@ title: Example Content File
 weight: 70
 ---
 
-Some things are better shown than explained. The following is a very basic example of a content file:
+Some things are better shown than explained. The following is a very basic example of a content file written in [Markdown](https://help.github.com/articles/github-flavored-markdown/):
 
-**mysite/project/nitro.md  ← http://mysite.com/project/nitro.html**
+**mysite/content/project/nitro.md → http://mysite.com/project/nitro.html**
 
-    ---
+With TOML front matter:
-    Title:       "Nitro : A quick and simple profiler for Go"
-    Description: "Nitro is a simple profiler for you go lang applications"
-    Tags:        [ "Development", "Go", "profiling" ]
-    date:        "2013-06-19"
-    Topics:      [ "Development", "Go" ]
-    Slug:        "nitro"
-    project_url: "http://github.com/spf13/nitro"
-    ---
 
-    # Nitro
+```markdown
++++
+date        = "2013-06-21T11:27:27-04:00"
+title       = "Nitro: A quick and simple profiler for Go"
+description = "Nitro is a simple profiler for your Golang applications"
+tags        = [ "Development", "Go", "profiling" ]
+topics      = [ "Development", "Go" ]
+slug        = "nitro"
+project_url = "https://github.com/spf13/nitro"
++++
 
-    Quick and easy performance analyzer library for Go.
+# Nitro
 
-    ## Overview
+Quick and easy performance analyzer library for [Go](http://golang.org/).
 
-    Nitro is a quick and easy performance analyzer library for Go.
+## Overview
-    It is useful for comparing A/B against different drafts of functions
-    or different functions.
 
-    ## Implementing Nitro
+Nitro is a quick and easy performance analyzer library for Go.
+It is useful for comparing A/B against different drafts of functions
+or different functions.
 
-    Using Nitro is simple. First use go get to install the latest version
+## Implementing Nitro
-    of the library.
+
+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.
+Next, include nitro in your application.
+```
 
+You may also use the equivalent YAML front matter:
 
+```markdown
+---
+date:        "2013-06-21T11:27:27-04:00"
+title:       "Nitro: A quick and simple profiler for Go"
+description: "Nitro is a simple profiler for your Go lang applications"
+tags:        [ "Development", "Go", "profiling" ]
+topics:      [ "Development", "Go" ]
+slug:        "nitro"
+project_url: "https://github.com/spf13/nitro"
+---
+```
+
+`nitro.md` would be rendered as follows:
+
+> # Nitro
+>
+> Quick and easy performance analyzer library for [Go](http://golang.org/).
+>
+> ## Overview
+>
+> Nitro is a quick and easy performance analyzer library for Go.
+> 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.
+
+The source `nitro.md` file is converted to HTML by the excellent
+[Blackfriday](https://github.com/russross/blackfriday) Markdown processor,
+which supports extended features found in the popular
+[GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/).

docs/content/content/front-matter.md

@@ -11,29 +11,19 @@ title: Front Matter
 weight: 20
 ---
 
-The front matter is one of the features that gives Hugo its strength. It enables
+The **front matter** is one of the features that gives Hugo its strength. It enables
 you to include the meta data of the content right with it. Hugo supports a few
 different formats, each with their own identifying tokens.
 
 Supported formats:
 
-  * **YAML**, identified by '`---`'.
+  * **[TOML][]**, identified by '`+++`'.
-  * **TOML**, identified with '`+++`'.
+  * **[YAML][]**, identified by '`---`'.
-  * **JSON**, a single JSON object which is surrounded by '`{`' and '`}`', each on their own line.
+  * **[JSON][]**, a single JSON object which is surrounded by '`{`' and '`}`', each on their own line.
 
-### YAML Example
+[TOML]: https://github.com/toml-lang/toml "Tom's Obvious, Minimal Language"
-
+[YAML]: http://www.yaml.org/ "YAML Ain't Markup Language"
-    ---
+[JSON]: http://www.json.org/ "JavaScript Object Notation"
-    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" ]
-    date: "2012-04-06"
-    categories:
-      - "Development"
-      - "VIM"
-    slug: "spf13-vim-3-0-release-and-new-website"
-    ---
-    Content of the file goes Here
 
 ### TOML Example
 
@@ -48,6 +38,22 @@ Supported formats:
     ]
     slug = "spf13-vim-3-0-release-and-new-website"
     +++
+    
+    Content of the file goes Here
+
+### YAML 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" ]
+    date: "2012-04-06"
+    categories:
+      - "Development"
+      - "VIM"
+    slug: "spf13-vim-3-0-release-and-new-website"
+    ---
+    
     Content of the file goes Here
 
 ### JSON Example
@@ -63,6 +69,7 @@ Supported formats:
         ],
         "slug": "spf13-vim-3-0-release-and-new-website",
     }
+    
     Content of the file goes Here
 
 ## Variables
@@ -71,22 +78,22 @@ There are a few predefined variables that Hugo is aware of and utilizes. The use
 any variable they want to. These will be placed into the `.Params` variable available to the templates.
 Field names are always normalized to lowercase (e.g. `camelCase: true` is available as `.Params.camelcase`).
 
-### Required
+### Required variables
 
 * **title** The title for the content
 * **description** The description for the content
 * **date** The date the content will be sorted by
 * **taxonomies** These will use the field name of the plural form of the index (see tags and categories above)
 
-### Optional
+### Optional variables
 
 * **redirect** Mark the post as a redirect post
 * **draft** If true, the content will not be rendered unless `hugo` is called with `--buildDrafts`
 * **publishdate** If in the future, content will not be rendered unless `hugo` is called with `--buildFuture`
 * **type** The type of the content (will be derived from the directory automatically if unset)
 * **weight** Used for sorting
-* **markup** (Experimental) Specify "rst" for reStructuredText (requires
+* **markup** *(Experimental)* Specify `"rst"` for reStructuredText (requires
-            `rst2html`) or "md" (default) for Markdown
+            `rst2html`) or `"md"` (default) for Markdown
 * **slug** The token to appear in the tail of the URL,
    *or*<br>
 * **url** The full path to the content from the web root.<br>

docs/content/content/organization.md

@@ -12,15 +12,15 @@ title: Content Organization
 weight: 10
 ---
 
-Hugo uses markdown files with headers commonly called the front matter. Hugo
+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
+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
+the rendered website. Without any additional configuration, the following will
 just work. Hugo supports content nested at any level. The top level is special
 in Hugo and is used as the [section](/content/sections).
 
@@ -35,7 +35,7 @@ in Hugo and is used as the [section](/content/sections).
             ├── first.md       // <- http://1.com/quote/first/
             └── second.md      // <- http://1.com/quote/second/
 
-**Here's the same organization run with hugo -\-uglyurls**
+**Here's the same organization run with `hugo --uglyurls`**
 
     .
     └── content
@@ -50,14 +50,14 @@ in Hugo and is used as the [section](/content/sections).
 
 ## Destinations
 
-Hugo thinks that you organize your content with a purpose. The same structure
+Hugo believes that you organize your content with a purpose. The same structure
 that works to organize your source content is used to organize the rendered
 site. As displayed above, the organization of the source content will be
 mirrored in the destination.
 
 There are times when one would need more control over their content. In these
-cases there are a variety of things that can be specified in the front matter to
+cases, there are a variety of things that can be specified in the front matter
-determine the destination of a specific piece of content.
+to determine the destination of a specific piece of content.
 
 The following items are defined in order, latter items in the list will override
 earlier settings.
@@ -84,10 +84,10 @@ path to the file on disk. Destination will create the destination with the same
 path. Includes [section](/content/sections).
 
 ### url
-A complete url can be provided. This will override all the above as it pertains
+A complete URL can be provided. This will override all the above as it pertains
 to the end destination. This must be the path from the baseurl (starting with a "/").
-When a url is provided it will be used exactly. Using url will ignore the
+When a url is provided, it will be used exactly. Using url will ignore the
--\-uglyurls setting.
+`--uglyurls` setting.
 
 
 ## Path breakdown in Hugo

docs/content/content/sections.md

@@ -10,7 +10,7 @@ title: Sections
 weight: 30
 ---
 
-Hugo thinks that you organize your content with a purpose. The same structure
+Hugo believes that you organize your content with a purpose. The same structure
 that works to organize your source content is used to organize the rendered
 site (see [Organization](/content/organization)). Following this pattern Hugo
 uses the top level of your content organization as **the Section**.

docs/content/overview/installing.md

@@ -11,10 +11,10 @@ title: Installing Hugo
 weight: 20
 ---
 
-Hugo is written in Go with support for Windows, Linux, FreeBSD and OS X.
+Hugo is written in Go with support for multiple platforms.
 
 The latest release can be found at [Hugo Releases](https://github.com/spf13/hugo/releases).
-We currently build for Windows, Linux, FreeBSD and OS X for x64
+We currently build for <i class="fa fa-windows"></i> Windows, <i class="fa fa-linux"></i> Linux, FreeBSD and <i class="fa fa-apple"></i> OS&nbsp;X for x64
 and i386 architectures.
 
 ## Installing Hugo (binary)
@@ -53,15 +53,15 @@ placed in your `PATH`.
 * Mercurial
 * Bazaar
 
-### Get directly from GitHub:
+### Get directly from GitHub
 
+    $ export GOPATH=$HOME/go
     $ go get -v github.com/spf13/hugo
 
-### Building Hugo
+`go get` will then fetch Hugo and all its dependent libraries to your
-
+`$GOPATH/src` directory, and compile everything into the final `hugo`
-    $ cd /path/to/hugo
+(or `hugo.exe`) executable, which you will find sitting in the
-    $ go build -o hugo main.go
+`$GOPATH/bin/hugo` directory, all ready to go!
-    $ mv hugo /usr/local/bin/
 
 ## Contributing
 

docs/content/overview/introduction.md

@@ -20,10 +20,17 @@ edited, Hugo is optimized for website viewing while providing a great
 writing experience.
 
 Sites built with Hugo are extremely fast and very secure. Hugo sites can
-be hosted anywhere, including Heroku, GoDaddy, GitHub Pages, Amazon S3
+be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][],
-and CloudFront, and work well with CDNs. Hugo sites run without dependencies
+[GitHub Pages][], [Amazon S3][] and [CloudFront][], and work well with CDNs.
-on expensive runtimes like Ruby, Python or PHP and without dependencies
+Hugo sites run without dependencies on expensive runtimes like Ruby,
-on any databases.
+Python or PHP and without dependencies on any databases.
+
+[Heroku]: https://www.heroku.com/
+[GoDaddy]: https://www.godaddy.com/
+[DreamHost]: http://www.dreamhost.com/
+[GitHub Pages]: http://www.dreamhost.com/cloud/
+[Amazon S3]: http://aws.amazon.com/s3/
+[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
 
 We think of Hugo as the ideal website creation tool. With nearly instant
 build times and the ability to rebuild whenever a change is made, Hugo
@@ -40,7 +47,7 @@ Hugo boasts the following features:
 ### General
 
   * Extremely fast build times (~1 ms per page)
-  * Completely cross platform: Runs on Mac OS X, Linux and Windows
+  * Completely cross platform: Runs on <i class="fa fa-apple"></i>&nbsp;Mac OS&nbsp;X, <i class="fa fa-linux"></i>&nbsp;Linux, <i class="fa fa-windows"></i>&nbsp;Windows, and more!
   * Easy [installation](/overview/installing)
   * Render changes [on the fly](/overview/usage) with [LiveReload](/extras/livereload) as you develop
   * Complete theme support
@@ -102,7 +109,7 @@ hacked blogs. I hated how content was written in HTML instead of the much
 simpler Markdown. Overall, I felt like it got in my way more than it helped
 me from writing great content.
 
-I looked at existing static site generators like Jekyll, Middleman and nanoc.
+I looked at existing static site generators like [Jekyll][], [Middleman][] and [nanoc][].
 All had complicated dependencies to install and took far longer to render
 my blog with hundreds of posts than I felt was acceptable. I wanted
 a framework to be able to get rapid feedback while making changes to the
@@ -110,12 +117,18 @@ templates, and the 5+-minute render times was just too slow. In general,
 they were also very blog minded and didn't have the ability to have
 different content types and flexible URLs.
 
+[Jekyll]: http://jekyllrb.com/
+[Middleman]: https://middlemanapp.com/
+[nanoc]: http://nanoc.ws/
+
 I wanted to develop a fast and full-featured website framework without
-dependencies. The Go language seemed to have all of the features I needed
+dependencies. The [Go language][] seemed to have all of the features I needed
 in a language. I began developing Hugo in Go and fell in love with the
 language. I hope you will enjoy using (and contributing to) Hugo as much
 as I have writing it.
 
+[Go language]: http://golang.org/ "The Go Programming Language"
+
 ## Next Steps
 
  * [Install Hugo](/overview/installing)

docs/content/themes/installing.md

@@ -9,21 +9,21 @@ title: Installing Themes
 weight: 20
 ---
 
-Hugo themes are located in a centralized github repository. [Hugo Themes
+Hugo themes are located in a centralized GitHub repository. The [Hugo Themes
 Repo](http://github.com/spf13/hugoThemes) itself is really a meta
 repository which contains pointers to set of contributed themes.
 
 ## Installing all themes
 
-If you would like to install all of the available hugo themes, simply
+If you would like to install all of the available Hugo themes, simply
-clone the entire repository from within your working directory.
+clone the entire repository from within your working directory:
 
 ```bash
-git clone --recursive https://github.com/spf13/hugoThemes.git themes
+$ git clone --recursive https://github.com/spf13/hugoThemes.git themes
 ```
 
 ## Installing a specific theme
 
-    mkdir themes
+    $ mkdir themes
-    cd themes
+    $ cd themes
-    git clone URL_TO_THEME
+    $ git clone URL_TO_THEME

docs/content/troubleshooting/strange-eof-error.md

@@ -24,17 +24,17 @@ Is there something that I am blatantly missing?
 
 ## Solution
 
-Thank you for reporting this issue.  The solution is to add a final newline (or EOL) to the end of your default.md archetype file of your theme.  More discussions happened on the forum here:
+Thank you for reporting this issue.  The solution is to add a final newline (i.e. EOL) to the end of your default.md archetype file of your theme.  More discussions happened on the forum here:
 
 * http://discuss.gohugo.io/t/archetypes-not-properly-working-in-0-12/544
 * http://discuss.gohugo.io/t/eol-f-in-archetype-files/554
 
-So yes, we do need to fix this.  We need to do the following:
+Due to popular demand, Hugo's parser has been enhanced to
+accommodate archetype files without final EOL,
+thanks to the great work by [@tatsushid](https://github.com/tatsushid),
+in the upcoming v0.13 release,
 
-1. Add warnings about this in the Hugo documentation, as several people have run into the same problem already.  (Users of editors like Vim, nano and gedit are immune to this because these editors enforce an EOL at the end of the file by default, but other editors like Emacs don't do that.)
+Until then, for us running the stable v0.12 release, please remember to add the final EOL diligently.  <i class="fa fa-smile-o"></i>
-2. Improve the error message.  It is difficult to determine what went wrong with just three characters "`EOF`"
-3. Allow archetype files without the final EOL to compile anyway, but do give an appropriate and detailed warning.  (optional, to be discussed)
-https://github.com/spf13/hugo/issues/776
 
 ## References
 

docs/content/tutorials/automated-deployments.md

@@ -112,7 +112,7 @@ Let's start by setting up an account for Wercker. To do so we'll go to www.werck
 
 ## Register
 
-To make life easier for ourselves, we will then register using GitHub. If you don't have a GitHub account, or don't want to use it for your account you can of course register with a username and password as well.
+To make life easier for ourselves, we will then register using GitHub. If you don't have a GitHub account, or don't want to use it for your account, you can of course register with a username and password as well.
 
 ![][4]
 

docs/content/tutorials/github_pages_blog.md

@@ -240,7 +240,7 @@ Step by step:
 2. Create on GitHub `<username>.github.io` repository (it will host the `public` folder: the static website)
 2. `git clone <<your-project>-hugo-url> && cd <your-project>-hugo`
 3. Make your website work locally (`hugo serve --watch -t <yourtheme>`)
-4. Once you are happy with the results, `Ctrl+c` (kill server) and `rm -rf public` (don't worry, it can always be regenerated with `hugo -t <yourtheme>`)
+4. Once you are happy with the results, <kbd>Ctrl</kbd>+<kbd>C</kbd> (kill server) and `rm -rf public` (don't worry, it can always be regenerated with `hugo -t <yourtheme>`)
 5. `git submodule add git@github.com:<username>/<username>.github.io.git public`
 6. Almost done: add a `deploy.sh` script to help you (and make it executable: `chmod +x deploy.sh`):