Well, since the advent of 0,13 has had me tinkering with my templates again, I’m afraid it’s back to headbutting walls in confusion with regard to trying to understand Hugo’s variables [both config and template]. Might as well flag the issue up again, since the new release is likely to be sending some traffic this way.
Much though I love Hugo, I’m afraid I find the documentation pretty opaque when it comes to accessing the various [pun intended!] variables… some seem to work with just {{ .varname }}, some need {{ .Site.varname }}, others need {{ .Data.varname }} or, {{ .Site.Params.varname }}, or just {{ .Params.varname }} or various combinations of all of those [and that’s without even mentioning the fact that some vars seem to be defined/referred to in some places using an initial capital letter and in others using all lower case].
Now I realise that this is because of the different scopes of the different variables and I’m prepared to wrestle with the complexities of that, but I think it would really help if someone on the project team could be charged with improving the documentation to make things a bit more explicit.
Here’s a concrete example of what I mean:
Flushed with the success of having just added pagination to my site, I thought I’d also add PREV and NEXT links inside my individual article pages too. So I fired up the Documentation and looked at the [Template Variables][1] page.
Under the section titled Page Variables, we see the following:
Page Variables
…
.Title The title for the content.
.Content The content itself, defined below the front matter.
.Summary A generated summary of the content for easily
showing a snippet in a summary view. Note that the breakpoint can be set
manually by inserting at the appropriate place in the content page. See Summaries for more details.
.Truncated A boolean, true if the .Summary is truncated. Useful for showing a “Read more…” link only if necessary. See Summaries for more details.
.Description The description for the content.
.Keywords The meta keywords for this content.
.Date The date the content is associated with.
.PublishDate The date the content is published on.
.Type The content type (e.g. post).
.Section The section this content belongs to.
.Permalink The Permanent link for this page.
.RelPermalink The Relative permanent link for this page.
.LinkTitle Access when creating links to this content. Will use linktitle if set in front matter, else title.
.Taxonomies These will use the field name of the plural form of the taxonomy (see tags and categories below).
.RSSLink Link to the taxonomies’ RSS link.
.TableOfContents The rendered table of contents for this content.
.Prev Pointer to the previous content (based on pub date).
.Next Pointer to the following content (based on pub date).
.PrevInSection Pointer to the previous content within the same section (based on pub date)
.NextInSection Pointer to the following content within the same section (based on pub date)
.FuzzyWordCount The approximate number of words in the content.
.WordCount The number of words in the content.
.ReadingTime The estimated time it takes to read the content in minutes.
.Weight Assigned weight (in the front matter) to this content, used in sorting.
.IsNode Always false for pages.
.IsPage Always true for page.
.Site See Site Variables below.
.Hugo See Hugo Variables below.
So I tried adding {{.Prev}} and {{.Next}} links into my single.html template and hugo server crapped out with a nil pointer error on one of the links and a 404 on the other. So, having been here before when working with vars in Hugo and just out of interest, I decided to output all the abovelisted page variables onto my pages, just to see what is actually being generated. So I made a quick HTML list and embedded it in the single.html template:
<li>TITLE: {{.Title}}</li>
<li>CONTENT: {{.Content}}</li>
<li>SUMMARY: {{.Summary}}</li>
<li>TRUNCATED: {{.Truncated}}</li>
<li>DESCRIPTION: {{.Description}}</li>
<li>KEYWORDS: {{.Keywords}}</li>
<li>DATE: {{.Date}}</li>
<li>PUBLISHDATE: {{.PublishDate}}</li>
<li>TYPE: {{.Type}}</li>
<li>SECTION: {{.Section}}</li>
<li>PERMALINK: {{.Permalink}}</li>
<li>RELPERMALINK: {{.RelPermalink}}</li>
<li>LINKTITLE: {{.LinkTitle}}</li>
<li>TAXONOMIES: {{.Taxonomies}}</li>
<li>RSSLINK: {{.RSSLink}}</li>
<li>TABLEOFCONTENTS: {{.TableOfContents}}</li>
<li>PREV: {{.Prev}}</li>
<li>NEXT: {{.Next}}</li>
<li>PREVINSECTION: {{.PrevInSection}}</li>
<li>NEXTINSECTION: {{.NextInSection}}</li>
<li>FUZZYWORDCOUNT: {{.FuzzyWordCount}}</li>
<li>WORDCOUNT: {{.WordCount}}</li>
<li>READINGTIME: {{.ReadingTime}}</li>
<li>WEIGHT: {{.Weight}}</li>
<li>ISNODE: {{.IsNode}}</li>
<li>ISPAGE: {{.IsPage}}</li>
</ol>````
I reloaded *hugo server* and got the following displayed on the page:
````1. TITLE: Brothword 0001
2. CONTENT: <snip>
3. SUMMARY: blah...blah...blah...
4. TRUNCATED: true
5. DESCRIPTION:
6. KEYWORDS: []
7. DATE: 2015-02-23 15:26:51 +0000
8. UTCPUBLISHDATE: 0001-01-01 00:00:00 +0000 UTC
9. TYPE: post
10. SECTION:
11. PERMALINK: http://localhost:1313/2015-02-13-brothword0001/
12. RELPERMALINK: /2015-02-13-brothword0001
13. LINKTITLE: Brothword 0001
14. TAXONOMIES:````
Not too bad so far, although some of the variables seem to be empty, even though they should have values [eg. `.Keywords`]. But why does the list stop at no. 14? A quick check of hugo server's output shows:
```ERROR: 2015/02/28 Error while rendering page .... executing "theme/_default/single.html" at <.Taxonomies>: Taxonomies is not a field of struct type *hugolib.Page````
OK. So for whatever reason, `.Taxonomies` doesn't work. I commented that line out of my list and reloaded *hugo server* again. Now I got:
`(1 to 13 as before)
...
14. RSSLINK:
15. TABLEOFCONTENTS:
16. PREV: %!v(PANIC=runtime error: invalid memory address or nil pointer dereference)
17. NEXT: %!v(PANIC=runtime error: invalid memory address or nil pointer dereference)
18. PREVINSECTION: %!v(PANIC=runtime error: invalid memory address or nil pointer dereference)
19. NEXTINSECTION: %!v(PANIC=runtime error: invalid memory address or nil pointer dereference)
20. FUZZYWORDCOUNT: 100
21. WORDCOUNT: 81
22. READINGTIME: 1
23. WEIGHT: 0
24. ISNODE: false
25. ISPAGE: true`
So, why do some of the template page variables [as listed in the Documentation] work as expected, some fail to return anything, some return an inline [ie. on the HTML page] error and one returns a hugo error at compile time?
**Parting thought:**
The irony is that, when you do find out how to do something with Hugo, it's usually beautifully simple to implement. I've just added the new pagination to my site with a couple of lines of template code and a few CSS tweaks. Took me about ten minutes. Unfortunately it took me nearly half an hour trying to make sense of the documention to fathom out exactly how and where to add the new code and configure it. I don't think I'm particularly stupid but I find a lot of Hugo's documentation pretty baffling.
Am I alone in this?
---
BTW: hugo version: Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30Z
[1]: http://gohugo.io/templates/variables/
