Documentation for template syntax, structure, and variables

support
1

I am new to Hugo. Always a confusing situation!
I am without any knowledge of go and I really do not want to learn. I have a lot of perl, c, and rust. Happy with that.
So my first question is: Am I in the right place, with Hugo? It does not seem I need to know go…
Next, after working through a few tutorials and playing with some sample sites and themes, I am ready to start editing and experimenting. But given some thing like:

{{ if .Params.clickablePhotos }}
    <div class="grid">
    {{ $images := .Resources.ByType "image" }}
    {{ range shuffle $images }}
    {{ $resized := .Resize $.Params.maxWidth }}
        <div>
            <a href="{{ .RelPermalink }}">
                <img src="{{ $resized.RelPermalink }}" alt="{{ .Name }}" />
            </a>
        </div>
        {{ end }}
    </div>
{{ else }}

I can make guesses as to what all this means, it seems straight forward enough. But there must be some place that this is all documented. I can find snippets here and there but no index where
.RelPermalink
range
.Resize
etcetera are listed so I cn check what they mean.

I have found resources explaining the template syntax (as opposed to the meanings of the keywords) but they are from the point of view of writing go code.

2

In my opinion, you don’t need to learn Go to use Hugo, but you do need to read the Hugo docs.

For example,

.RelPermalink
range
.Resize

are all documented: using the search bar in the docs should give you results.

3

Thank you. Duh! I should have entered those in the search bar. Sigh. Obvious…

4

It was helpful. But I do need a index, as search does not allways work. Here are two examples:

{{ template "_internal/twitter_cards.html" . }}
{{ template "_internal/opengraph.html" . }}
{{ template "_internal/google_analytics_async.html" . }}

I found that in a template. As far as I can see it has no effect.
Searching for template does not help. I am not sure what this syntax means.

There is no directory names _internal and no file named twitter_cards.

And this from call-me-sam theme:

                {{ range .Site.Params.mainMenu }}
                    <div class="big-link">
                        <a href="{{.link}}">
                          {{.text}}
                        </a>
                    </div>
                {{ end }}

link is not defined that I can find. I know it is defined, but I cannot find it by entering “link” in the search box.

5

Those are internal templates: Internal templates | Hugo

They may need additional configuration before they are usable. The Google Analytics template for example needs a tracking ID in your config.

Generally, *.Params contain custom (ie user-defined) variables.

Hugo-defined variables are all here: Variables | Hugo

In this case, the theme author has documentation on how to configure that: GitHub - victoriadrake/hugo-theme-sam: A Simple and Minimalist theme for Hugo with a focus on typography and content.

6

How am I to know that {{ template <thing> }} is pointing to a internal template? Not that syntax specifically but more generally? When I see a key word, I would like to look it up in a index. The search function is great when it is good but not what I need a lot of the time.
Same for .link.
One method is to make a post here every time, but I am afraid of wearing out my welcome.

7

If you paste template "_internal/twitter_cards.html" into the search box, it gives you that page.

The left sidebar on the docs page includes the main doc sections, which include Templates, Functions, and Variables. They are all listed there.

If a code snippet is included in a theme and it’s not documented on the Hugo docs, there’s a good chance the theme author has some kind of guide for how it is supposed to be used.

This discourse also has a search bar.

Other than the theme example above, what keywords have you tried that have not returned results on the docs page?

8

.link is a example.

9

@Worik we don’t have an index of terms, we have the documentation site. Everyone contributes to make it better, maybe you will be the one that builds an index. :slight_smile:

If you need help with specific code, ask the person that wrote it. If it’s in a theme, ask in their issue tracker. Or, open a new support ticket after reading Requesting Help. Hugo is very complex, and I recommend you read every page in the docs, to start.

1 Like
10

The search system is very good, after using it for a day