ref: e425226a2802993f4be3689565136965fb5bc58c
parent: 07978e4a4922bc21c230fee65052232b829bd1ab
author: Phil Pennock <[email protected]>
date: Mon Nov 18 13:31:02 EST 2013
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 <[email protected]>
binary files /dev/null b/docs/content/extras/permalinks.md differ
--- a/docs/content/layout/go-templates.md
+++ b/docs/content/layout/go-templates.md
@@ -6,13 +6,64 @@
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 © 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/>
--- a/docs/content/layout/variables.md
+++ b/docs/content/layout/variables.md
@@ -52,5 +52,5 @@
**.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>
--- a/docs/content/meta/release-notes.md
+++ b/docs/content/meta/release-notes.md
@@ -36,6 +36,8 @@
* 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
--- a/docs/content/overview/configuration.md
+++ b/docs/content/overview/configuration.md
@@ -8,12 +8,12 @@
---
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 @@
indexes:
category: "categories"
tag: "tags"
- baseurl: "http://yoursite.com/"
+ baseurl: "http://yoursite.example.com/"
...
@@ -44,7 +44,7 @@
"category": "categories",
"tag": "tags"
},
- "baseurl": "http://yoursite.com/"
+ "baseurl": "http://yoursite.example.com/"
}
@@ -54,8 +54,25 @@
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
+ ...