Hugo All Kinds Theme

Hugo theme for handling all kinds of pages

Things I learned about Hugo

Things I learned about Hugo while developoing a new theme and complaints I still have.

Learnings

  • Inheritibility is available, but limited. .Title pulls from current page or config, and anything under [params] likewise via .Param KEY . Nothing I’ve found would look in current page, front matter of current section then config, though.
  • Argument passing is manual for partials, same thing for shortcodes is weird. There should be a systematic way to pass page context to partial along with any args. Best I can come up with is: {{partial "foo" (dict "page". "argv" (slice ...))}}. Utility partials need arguments, but maybe most page partials don’t?
  • Remember that $. is the value of . when template (or partial) was invoked.

Residual Complaints

Gripes about doc

Try to characterize what’s bad about documentation.

  1. It’s all ad-hoc, just-so. It’s never concise and comprehensive. Add examples here:
    1. Should be one authoritative section on template inheritance, which clarifies kind, section and type, covers baseof vs list and single (any others?).
  2. It’s not object oriented. Just a flat list of variables another of methods, etc.
  3. (in https://gohugo.io/hugo-pipes/js/, e.g) Hugo Module “virtual union file system” is just “search path” by a different name. Confusing!

Gripes about Hugo itself

  1. It badly needs pruning. New (better) features supplant older ways of doing things, but (in the name of backward compatibility? Or just rapid evolution?) old ways are not deprecated. Doc should always favor the new thinking, relegating old thinking to appendices. Some examples:
    1. Description (in .Params) vs Summary (

break). Probably really are different, but doc simply says both exist. In list indices, they might be interchangable, though. [[doc thing?]] 2. Can’t extend. Eg, In Go templates, you can register user-provided functions and invoke them in the template. But you’d have to extend Hugo to do this. Maybe that’s just a “feature” of Golang itself. No DLL mechanism, for better or worse. 3. “Simple” features with (to me) arbitrary limitations (like inheritance above). “Make things as simple as you can, but no simpler”. More examples:

  1. asdf
  2. non-Ugly URLs are the default style and are not pretty for everyone. (I think this is an example of one man’s simple being another man’s WTF). But at least the bootstrap4-blog theme hand-crafts URIs in partials, so this is hard to fix with one global switch. Maybe Hugo does have a canonic way of abstracting these? But there’s a welter of rel- and abs- URL functions and some that just do one or the other. I’m not finding it “simple” (there’s that word again). Some current doc would help.

Open questions

  1. [Resolved] Page properties inheritable from section? Then project index could default project name, category. And new page might only have a few distinguishing props.

    Not in general. But section list template can refer to .Section or similar to access parameters defined exclusively in section _index.md. Page cannot override.

    Cannot, e.g define category or tags in section index, that will remain a page-specific thing.

  2. But see: $.Params – documented to look first in page FM, then in site paramaters.

  3. can use slice A B C to invoke (a partial) with a list of things, or dict K1 V1 K2 V2 ... to invoke with a property bag.

  4. Modified date provided automatically?

  5. If no Title, name from file name | title?

  6. [resolved] template folder structure follows content (e.g content/{blog, projects} ==> layout/{blog,projects}/{list,single}.html). Hugo page.Type is the best variable to distinguish templates (better than .Section or .Kind, I think?)

  7. $. refers to initial value of . when template invoked.