From 77a62527aaf598801c625d5fd1758e85604805a2 Mon Sep 17 00:00:00 2001 From: Phil Pennock Date: Mon, 18 Nov 2013 18:31:02 -0500 Subject: [PATCH] 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 --- docs/content/extras/permalinks.md | 33 ++++++++++++++ docs/content/layout/go-templates.md | 61 +++++++++++++++++++++++--- docs/content/layout/variables.md | 4 +- docs/content/meta/release-notes.md | 2 + docs/content/overview/configuration.md | 31 ++++++++++--- 5 files changed, 117 insertions(+), 14 deletions(-) create mode 100644 docs/content/extras/permalinks.md 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 . + 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 `