First impression

support
1

First project, 2 days of trying to make it work, so far so good, but fighting it every step of the way because it behaves like a black box. I thought I’d post this as feedback while I am at it.

  1. The docs are good, but a lot of the details is either missing or is scattered across different sections. E.g. config log and logFile. I set log = true + hugo server -v - no log. I added 'logFile = “log.txt”`, still nothing. The same with an absolute path, still no log. Where does it write it? What’s missing?

  2. The logic of the site building is a black box. Why did it ignore the content I’ve just added? Why is it using a wrong layout? I have to spend hours makinging seemingly random changes to figure it out.
    What would be good is to have a detailed log where it reasons about the decision tree. E.g. looking at dir X, found index.md, content type …, layout …, ignoring file …, and so on.

  3. Some core types are obscure. e.g. nopPage. A quick lookup tells me it’s a Page that does nothing. Not very helpful because I have no idea WHY it got this nop when I expected some page there.

I’d love to contribute, but Go is not in my stack. Happy to chip in with the docs if you think this kind of PRs will be considered by maintainers.

3 Likes
2

The documentation has a search field. Use it and check all results. It’s true, it’s hidden sometimes.

Configuration documentation: Configure Hugo | Hugo

log (false)
Enable logging.

logFile (“”)
Log File path (if set, logging enabled automatically).

That is very understandable even to me (I am also not a Go developer). Set log to true to log. Set logFile to “hugo.log”. Run hugo server and the logfile appears.

nopPage: So, where are you getting this?

Documentation Repo: GitHub - gohugoio/hugoDocs: The source for https://gohugo.io/, PRs welcome.

making seemingly random changes to find out how it works: I would read the documentation from start to end just once. You will get a feeling where you have to look for what. It is scattered, but if you check the issues of the docs repo you see a ticket with an effort to restructure the documentation.

everything else: ask :wink: put sample code up. put a sample repo somewhere. say what you expected and what instead happened and you will get answers. I guess we all (except the devs) learned the intricacies of Hugo only with the forum.

3 Likes