Documentation updates, mostly for my bits

* extras/permalinks.md added, weighted to third in the extras menu
* examples added to layout/go-templates.md, using `.Site.Params`
* mention `.Site.Params` in layout/variables.md
* update meta/release-notes.md to mention `first` and the permalinks
* update overview/configuration.md to use reserved-for-documentation
  domains and with another example, nudging towards permalinks and site
  parameters, with three different data-types shown for the latter

Signed-off-by: Noah Campbell <noahcampbell@gmail.com>

5 files changed, 116 insertions, 13 deletions

diff --git a/docs/content/extras/permalinks.md b/docs/content/extras/permalinks.md
new file mode 100644
index 000000000..e76b224d3
--- /dev/null
+++ b/docs/content/extras/permalinks.md
@@ -0,0 +1,33 @@
+---
+title: "Permalinks"
+date: "2013-11-18"
+aliases:
+  - "/doc/permalinks/"
+groups: ["extras"]
+groups_weight: 30
+---
+
+By default, content is laid out into the target `publishdir` (public)
+namespace matching its layout within the `contentdir` hierarchy.
+The `permalinks` site configuration option allows you to adjust this on a
+per-section basis.
+This will change where the files are written to and will change the page's
+internal "canonical" location, such that template references to
+`.RelPermalink` will honour the adjustments made as a result of the mappings
+in this option.
+
+For instance, if one of your sections is called `post` and you want to adjust
+the canonical path to be hierarchical based on the year and month, then you
+might use:
+
+```yaml
+permalinks:
+  post: /:year/:month/:title/
+```
+
+Only the content under `post/` will be so rewritten.
+A file named `content/post/sample-entry` which contains a line
+`date: 2013-11-18T19:20:00-05:00` might end up with the rendered page
+appearing at `public/2013/11/sample-entry/index.html` and be reachable via
+the URL <http://yoursite.example.com/2013/11/sample-entry/>.
+
diff --git a/docs/content/layout/go-templates.md b/docs/content/layout/go-templates.md
index b9a8f5838..093497cdb 100644
--- a/docs/content/layout/go-templates.md
+++ b/docs/content/layout/go-templates.md
@@ -6,13 +6,64 @@ groups_weight: 80
 draft: true
 ---
 
-Hugo uses the excellent golang html/template library for its template engine.
+Hugo uses the excellent [golang][] [html/template][gohtmltemplate] library for
+its 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
+logic.
+In our experience that it is just the right amount of logic to be able to
 create a good static website.
 
-This is a brief primer on using go templates. The [golang
-docs](http://golang.org/pkg/html/template/) provide more details.
+This is a brief primer on using go templates. The [golang docs][gohtmltemplate]
+provide more details.
 
+In your top-level configuration file (eg, `config.yaml`) you can define site
+parameters, which are values which will be available to you in chrome.
 
+For instance, you might declare:
 
+```yaml
+params:
+  CopyrightHTML: "Copyright &#xA9; 2013 John Doe. All Rights Reserved."
+  TwitterUser: "spf13"
+  SidebarRecentLimit: 5
+```
+
+Within a footer layout, you might then declare a `<footer>` which is only
+provided if the `CopyrightHTML` parameter is provided, and if it is given,
+you would declare it to be HTML-safe, so that the HTML entity is not escaped
+again.  This would let you easily update just your top-level config file each
+January 1st, instead of hunting through your templates.
+
+```
+{{if .Site.Params.CopyrightHTML}}<footer>
+<div class="text-center">{{.Site.Params.CopyrightHTML | safeHtml}}</div>
+</footer>{{end}}
+```
+
+An alternative way of writing the "if" and then referencing the same value is
+to use "with" instead, which rebinds the pointer `.` within its scope, and
+elides the scope if the variable is absent:
+
+```
+{{with .Site.Params.TwitterUser}}<span class="twitter">
+<a href="https://twitter.com/{{.}}" rel="author">
+<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
+ alt="Twitter"></a>
+</span>{{end}}
+```
+
+Finally, if you want to pull "magic constants" out of your layouts, you can do
+so, such as in this example:
+
+```
+<nav class="recent">
+  <h1>Recent Posts</h1>
+  <ul>{{range first .Site.Params.SidebarRecentLimit .Site.Recent}}
+    <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
+  {{end}}</ul>
+</nav>
+```
+
+
+[golang]: <http://golang.org/>
+[gohtmltemplate]: <http://golang.org/pkg/html/template/>
diff --git a/docs/content/layout/variables.md b/docs/content/layout/variables.md
index 18ddadae1..5aa94b7e5 100644
--- a/docs/content/layout/variables.md
+++ b/docs/content/layout/variables.md
@@ -52,5 +52,5 @@ Also available is `.Site` which has the following:
 **.Site.BaseUrl** The base URL for the site as defined in the config.json file.<br>
 **.Site.Indexes** The indexes for the entire site.<br>
 **.Site.LastChange** The date of the last change of the most recent content.<br>
-**.Site.Recent** Array of all content ordered by Date, newest first<br>
-
+**.Site.Recent** Array of all content ordered by Date, newest first.<br>
+**.Site.Params** A container holding the values from `params` in your site configuration file.<br>
diff --git a/docs/content/meta/release-notes.md b/docs/content/meta/release-notes.md
index caa6b43e6..f8d835c83 100644
--- a/docs/content/meta/release-notes.md
+++ b/docs/content/meta/release-notes.md
@@ -36,6 +36,8 @@ groups_weight: 10
   * Better handling of most errors with directions on how to resolve
   * Support for more date / time formats
   * Support for go 1.2
+  * Support for `first` in templates
+  * Support for site per-section permalink pattern specifications
 * **0.8.0** August 2, 2013
   * Added support for pretty urls (filename/index.html vs filename.html)
   * Hugo supports a destination directory
diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md
index 8cc9b5858..6ac0035de 100644
--- a/docs/content/overview/configuration.md
+++ b/docs/content/overview/configuration.md
@@ -8,12 +8,12 @@ groups_weight: 40
 ---
 
 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.
+configuration for a site. In fact a config file isn't even needed for many
+websites since the defaults used follow commonly used patterns.
 
 Hugo expects to find the config file in the root of the source directory and
-will look there first for a config.yaml file. If none is present it will
-then look for a config.json file, followed by a config.toml file.
+will look there first for a `config.yaml` file. If none is present it will
+then look for a `config.json` file, followed by a `config.toml` file.
 
 **Please note the field names must be all lowercase**
 
@@ -29,7 +29,7 @@ The following is an example of a yaml config file with the default values:
     indexes:
        category: "categories"
        tag: "tags"
-    baseurl: "http://yoursite.com/"
+    baseurl: "http://yoursite.example.com/"
     ...
 
 
@@ -44,7 +44,7 @@ The following is an example of a json config file with the default values:
            "category": "categories",
            "tag": "tags"
         },
-        "baseurl": "http://yoursite.com/"
+        "baseurl": "http://yoursite.example.com/"
     }
 
 
@@ -54,8 +54,25 @@ The following is an example of a toml config file with the default values:
     layoutdir = "layouts"
     publishdir = "public"
     builddrafts = false
-    baseurl = "http://yoursite.com/"
+    baseurl = "http://yoursite.example.com/"
     [indexes]
        category = "categories"
        tag = "tags"
 
+Here is a yaml configuration file which sets a few more options
+
+    ---
+    baseurl: "http://yoursite.example.com/"
+    title: "Yoyodyne Widget Blogging"
+    permalinks:
+      post: /:year/:month/:title/
+    params:
+      Subtitle: "Spinning the cogs in the widgets"
+      AuthorName: "John Doe"
+      GitHubUser: "spf13"
+      ListOfFoo:
+        - "foo1"
+        - "foo2"
+      SidebarRecentLimit: 5
+    ...
+