Is there a systematic description of the Hugo API somewhere, listing all functions eg with a list of parameters, types, default values, etc?
By way of background:
I use Hugo for a site that I run, and I like it, but every time I try and add a new feature to my site it feels excruciatingly painful. I find myself scouring through the Hugo docs, never finding quite what I want, and then reading every post I can find on the topic, usually without success.
For example, yesterday I wanted to do something I thought would be simple: create a list of tutorial posts by topic. So I created a subdirectory under /content called /tutorials, and then put a bunch of subdirectories under there (with titles like “intro”, “expert”, etc) and then posts inside those. It seemed from the site content documentation that I would get a section for each of these subdirectories, as well as a higher level section for /tutorials. So I assumed I could use something like /groupBy “Section”/ to show each section and its posts. But I just couldn’t get it to work, and eventually realized it’s because I couldn’t find any clear documentation on how to navigate the section hierarchy – or even if there was a section hierarchy. The site content documentation made it clear that sections form a tree, but gave no hint about how to navigate this tree. In the end I realized I didn’t need sections at all and could just use the page hierarchy, but I just stumbled over that, and there was nothing I could find that explained in detail how a page can have subpages etc.
Am I off the mark? Is there a documentation library somewhere that I haven’t discovered? Or are these functions like groupBy from a Go library somewhere that’s documented?
I’d like to recommend Hugo to my students but this is currently a major impediment…
A lot of functions are “pulled” through from go-libraries like go-fmt (fmt package - fmt - Go Packages), others are implemented by Hugo. This “pulling through” though is not a full mirroring of functions. Only the ones deemed safe are implemented.
There is no API documentation where each single function and variable of gohugo has some documentation that is automatically fetched and compiled into a documentation. If there is a tool that does collect and compile Golang code into an API documentation you could use that to do so.
The documenation has a search powered by Algolia. I would type that into there and look through the results. Not fighting for or representing the documentation here
I rely heavily on Google (“gohugo searchterms”) for my research. The “gohugo” part largely works with the domain name and has results from the docs as first items.
Not trying to be argumentative, but to give a sense of what I’m finding hard about this: the layout I started with from the PaperMod theme has this code in it
{{- range $pages.GroupByPublishDate "2006" }}
{{- if ne .Key "0001" }}
and I couldn’t figure out what type of object is being returned by the range iteration (a composite object with a .key attribute and a .pages attribute?) and if the key is a date, why it would ever have the value “0001”…
Without a greater example I have no idea why a page object would have a .Key variable. This is probably too specific.
Having said that, the first line looks like you a trying to create some form of calendar and items WITHOUT any date information in the frontmatter tend in Gohugo be in the year 0001. It’s a “hack” for a deeper issue that is not connected to the documentation but to missing sanitation of frontmatter used.
My guess is that GroupBy produces a set of group objects, and the range iterator then produces one group object for each iteration. Then, as you suggest, maybe pages that don’t have a publish date appear in a group against a dummy year “0001”, so the author of PaperMod has accounted for that by simply excluding all such pages from the layout. Anyway, these are the questions API docs would answer, no?
) at 