Developer productivity related feedback. Multiple issues; needs triage from core team member

1

Hello,

I’m trying out Hugo and ended up chronicling some of the many stumbles that I think could have been avoided. Not all of these are easily addressable, but I’d like to bring them up anyway, in case there is interest in fixing some of them.

Instead of filing separate bugs, I figured it would be best to file a single issue capturing all the details, and for a project maintainer with more historical context to step in and triage appropriately, and perhaps filing specific bugs as needed.

Here are the things I noted.

  • Naming inconsistencies:

    • CLI requires --canonifyURLs; config.toml equivalent is canonifyurls (different case)
    • CLI requires --destination; config.toml equivalent is publishDir.
    • baseURL versus canonifyurls: should acronyms be CamelCase, or UPPERCASE?
    • DefaultContentLanguage versus languageCode: should the first letter be lower-case or upper-case?

  • Capitalization in many places seems arbitrary. A parameter named baseUrl is accessed as .Site.BaseUrl (note, upper case B), while a custom parameter named fooBar is accessed as .Params.foobar (note, all lower case).

  • Templates, layouts, themes, sections, types, etc. are all closely-related yet distinct terms, making them confusing. Even for someone well-experienced in other static page generators, the official docs add to the confusion instead of trying to explain what the specific terms mean. It would be nice to have a single page describing these high-level concepts in relation to one another. Users currently have to follow trails through multiple links to figure out what these basic terms mean.

  • Layouts are specified in a layouts/ directory but invoked using a type = layout_name parameter.

  • Homepage is special, and must be named _index.md. Simply doing the straightforward thing (as you would in any other directory) and putting a index.md (no leading underscore) ends up rendering a blank page using the (again, special!) home page template, but with no content (because, of course, Hugo was only looking for a _index.md and completely ignored the index.md that was, in fact, present.) There are no warnings about this; users are expected to figure this out on their own.

  • Error messages are confusing. Specific example: Even when the tool fails to generate many many files, the final summary numbers are still for the full set of files it processed, not subtracting any that were skipped because of errors.

  • Things that should be errors are instead WARNings and hidden in the default output unless --verbose is turned on. Basic errors such as pointing to non-existent templates and layout files should be flagged even without --verbose.

  • {{- .Title -}} should have been the default instead of {{ .Title }}.

  • When running as hugo server --watch, deleting the publishDir should also trigger a re-publish.

Thanks for listening!

2

I am gonna answer a couple of these, to see if we can resolve them before the weird ones are addressed.

Add Content and Front Matter to the Homepage:

The homepage, similar to other list pages in Hugo, accepts content and front matter from an _index.md file. This file should live at the root of your content folder (i.e., content/_index.md). You can then add body copy and metadata to your homepage the way you would any other content file.

Maybe we can point out that the homepage isn’t a single template somewhere earlier in the docs, but that seems pretty straightforward from the home page docs.

Where? That is normally used in templates, so which use are you referring to?

Why do you suggest that? Hugo isn’t publishing to that directory when you are running it as a server, and the contents of publishDir shouldn’t change how anything is created. What is your use case?

What is the issue with the layouts? It isn’t apparent to me. :slight_smile:

It is a lot to take in. However, if you want to add a page like that, I am sure others would find it useful.