The following is my very basic understanding of what’s going on in my current home template, and how to change it to get what I want (which is a generic introduction text containing some links) instead of a list of posts from ALL sections, which is what I have now.
What I did is to look at basof, the hompage (index) template, and comparing to the rendered html in my public folder. I searched terms in hugo documents as I read through, using knowledge of what I read already.
Here we go:
My theme does indeed has a baseof, which I understand to be a fundamental building block that contains a “meta-template.” In my case:
{{ partial "head.html" . }}
<body class="{{ .Site.Params.themeColor }} {{if .Site.Params.layoutReverse}}layout-reverse{{end}}">
{{ partial "sidebar.html" . }}
<main class="content container">
{{ block "main" . -}}{{- end }}
</main>
This chunk is responsible for creating the color for the nav bar at the side (params.themeColor), of which I have 8 options, this is described in the theme’s page. It also contains instructions to include the sidebar and the content container, defined as “main”.
OK, so knowing that I can take a look at my index.html inside layouts:
{{ define "main" -}}
<div class="posts">
{{ range .Data.Pages -}}
<article class="post">
<h1 class="post-title">
<a href="{{ .Permalink }}">{{ .Title }}</a>
</h1>
<time datetime="{{ .Date.Format "2006-01-02T15:04:05Z0700" }}" class="post-date">{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
{{ .Summary }}
{{ if .Truncated }}
<div class="read-more-link">
<a href="{{ .RelPermalink }}">Read More…</a>
</div>
{{ end }}
</article>
{{- end }}
</div>
{{- end }}
right from start, I can see it only deals with the main part and not the navigation bar. Makes sense since the nav bar is defined in the partials library and is unchanged. Now I’m trying to get a crack at what I’m looking at here:
{{define "main"}} - this line says, "this whole thing defines what is ‘main’.
<div...> - this is regular HTML, calling for div “posts”. This means we are now defining “posts”.
{{ range .Data.Pages -}} - not sure what this means. Hugo speaks of range being used just as in Go. It is the range of Data.Pages, which are .toml (in my case). I guess it basically calls to use all pages that are .toml on the site. Again, not sure which ones (I think all of them) and it looks generic, leaving this alone.
<article class="post"> - this tells me that now the template is starting to take care of the actual content. Up until now, it was generic definitions and calling different bits from somewhere else. This is where “article” is defined, from this line forward.
Now this is where opening the html from the doc folder (otherwise known as “public” to render the html) is somewhat helpful.
<h1 clas...> ok, this calls the title of the post. This also tells me this is the building block that starts posting my posts on the main page, complete with the link to it. I can guess what .Permalink and .Title do 
<time datetime...> this defines how the timestamp is formatted in Hugo, I saw the part on that (how it’s formatted).
{{.Summary}} The next chunk is a summary of my post, with a conditional that prepares a link of “read it more”. OK.
Next, it’s the end of defining article, and of defining posts.
So here, what I have is the piece that alaready calls the summary of posts and defines them. It looks like what would be a list template. This theory seems to be true because other lists on the theme would look the same.
Looking at all of this, I know I want to create a home template with these general points I’ve learned:
- I want to use the baseof template, which calls for the navigation bar at the left, and the content at the right. So, the homepage template should be under baseof in terms of what comes first, because the home page will also have the nav bar that is used throughout the whole site.
- I am not sure how the range work here or what it does, but I guess I can leave it alone because I only care for not having summaries of my posts on the first page… however, the main part is a problem. This is because it is defined here, in the homepage template. If I leave it alone, the next list template (which I guess have a “main” part) would simply plant my introdctory text and all with it, because I’m going to put it under. SO, I need to take the main part and put it in the list template which is under defaults, because it’s under homepage in terms of what comes first, and the rest of the site can still use it.
- I want to remove the whole
<article> bit from my home template. It should, instead, contain text (which I will put in, just introduction) and links inside of that text. Only one link, to my blog, should be pointing somewhere inside hugo (should be pointing to the list templates inside my blog section) and the rest will be outside of this website. Again, the <article> bit needs to be in the list template in default instead.
How does this sound so far…?
Looking at my list.html in _default, I see it too has {{define "main -}}. And so is single.html. So, we do not define it there, it’s something Hugo has built in… I can’t find reference to it or what it does. Maybe that’s because we DO define it, but main is defined differently, depending on which file we’re looking at. This means that baseof calls to two basic things: nav bar and main, where main is defined depending on which part we’re looking at in the website.
homepage has its own main, so does single, so does list.
If that’s true, I do not need to remove the main part from the homepage template. But, how does Hugo knows which “main” to use where? This must be determined by the order of importance, as the documents state. homepage is unique, which means its main is unique, and would not be repeated anywhere else…
Interesting.
