diff options
author | Phil Pennock <pdp@spodhuis.org> | 2013-11-18 18:31:02 -0500 |
---|---|---|
committer | Noah Campbell <noahcampbell@gmail.com> | 2013-11-18 15:51:31 -0800 |
commit | e425226a2802993f4be3689565136965fb5bc58c (patch) | |
tree | 62fda6a16b3aa074d5d24b25ae90aeb3ecaba20a | |
parent | 07978e4a4922bc21c230fee65052232b829bd1ab (diff) |
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>
-rw-r--r-- | docs/content/extras/permalinks.md | 33 | ||||
-rw-r--r-- | docs/content/layout/go-templates.md | 59 | ||||
-rw-r--r-- | docs/content/layout/variables.md | 4 | ||||
-rw-r--r-- | docs/content/meta/release-notes.md | 2 | ||||
-rw-r--r-- | docs/content/overview/configuration.md | 31 |
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 © 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 + ... + |