Debugging hugo: why a file in content is not arriving in the output?

[netchild]

Hi,

Context:
I try to convert my private website from an age old templating software (WML) to hugo. It contains various files, static pages, and php pages. The first step was to put everything I had into static/ (-> success). Next step is now to convert page by page to content/ with my own theme (partial/header.html , partial/footer.html, _default/single.html and index.html are populated with content) which matches what I had there before (1:1 conversation, just changing the backend). So far I managed to convert the index page (2 languages, index.en.html + index.de.html) successfully (this change is live). The output looks like I want to have it. This is not a blog like setup, it is old-style-pages setup. You can check https://www.leidinger.net/ for what I want to do, specially follow the link to “X11” (which is coming from “static/” so far) and what is linked from this page (this is creating me the most headaches so far, see below).

Issue(s):

• I have several pages on the same level, not only /index.html but also /a.html or /b.html. When I try to mimic the same in hugo nothing gets created in the output directory. With a different template I once got a subdirectory with the name of the page, e.g. /a/index.html, but currently I don’t. Both is not expected. While the subdirectory is probably a misunderstanding on how hugo should work, not generating something at all is unexected (see also following point).
• When I create content/X/index.en.html, nothing is generated (yes, “draft: false” for the file in question). The same for content/X/somethingelse.html or content/testhugo.html.
• hugo tells me that there is a duplicate target path (for /index.hml), but it does not tell me which files are mapping to the same output filename.

Main questions:

• How to tell hugo to tell me which files it tries to touch (source + dest) and why it does or does not create an output file? e.g. loading theme/mytheme/partial/header.html, …, not generating output file due to draft=true, …
• How to convince hugo to tell me which files are mapping to the same target filename?
  or in short: How to tell hugo to make his work more observable? (= basic stuff which you need to have when you need to debug something)

What I tried so far:

• enable “–verbose”
• enable “–log”
• enable “–debug”
• enable combinations of the options above
• add to each page: {{ warnf “Processing %q as type %q/%q (draft: %d)” .File.Path .Kind .Type .Draft }} -> results in no log output at all
• add to each file of the template: {{ warnf “Processing %q as type %q/%q (draft: %d)” .File.Path .Kind .Type .Draft }} -> results in printing some output for index.en.html, but not the output as I hoped for (print out each template filename)

I have spend hours on this, including googling around what I may have wrong in my template. I stumbled upon various posts which try to add some debugging on their own, but far from something useful in this situation (a little bit “you get no output at all” vs. “having some output files which do not contain what you want to get”).

Bye,
Alexander.

[pointyfar]

Hi there,

Please have a read about Requesting Help because it’s difficult to help you without seeing your site context and configuration. It’s easier to clone your site than to attempt to recreate your setup.

Generally, Hugo will render your site to match the structure of your content:

• https://gohugo.io/content-management/organization/
• https://gohugo.io/content-management/page-bundles/

So:

content/foo.md => yoursite.com/foo/

Collisions might occur when you have different content files that may render into the same URL. If for example the above page foo.md were transformed into a page bundle:

content/foo/index.md => yoursite.com/foo/

If you retain foo.md then both content files will try to be rendered to the same URL.

---

That is just one scenario where it might occur. There are others. Again, it is easier to help you if we can see your site code.

[netchild]

Hi,

Does this mean there is no way to tell hugo to be more transparent in what it is doing? This means debugging by trial and error?

I have uploaded a minimal example to
https://www.leidinger.net/test/hugo_site.tar.bz2 (20 KB)

In contains my theme, the content, and the config. Not included is everything in static (which is huge). When I run hugo on this, only /index.html and /de/index.html is generated from my content (and the theme files and 404 and the /en/ alias). Not generated is everything else, like the content/X/* and content/testhugo.html.

Bye,
Alexander.

[pointyfar]

Your link points to a 404.

[netchild]

Sorry, try again.

[netchild]

Does the silence here mean that there is no way to make hugo more transparent in case of issues (so I better wait to use it for real work until it is at a maturity level were it is possible to debug such issues)?

[alexandros]

According to your link you have the following:

content
├── X
│   ├── XKEYBOARD.de.html
│   ├── XKEYBOARD.en.html
│   ├── index.de.html
│   ├── index.en.html
│   ├── security.html
│   ├── test.html
│   ├── xdm-advanced.html
│   ├── xdm.html
│   ├── xhost.html
│   └── xresources.wml
├── index.de.html
├── index.en.html
├── projects.de.html
├── projects.en.html
└── testhugo.html

No wonder you are missing pages.

Please have a really good look at Page Bundles in the Documentation.

Do look in particular the difference between _index.md and index.md.
What sort of bundle does index.md create?

Also search the forum. The “issue” you experience has been discussed many many times in the past.

[netchild]

The docs are confusing, or at least not complete. The table in the beginning tells in “Allowed Resources” that for branch bundles “page resources” are not allowed, but I have e.g. xhost.html as of type “page” and it is generated, but _index.html of type page is not generated. The warning about duplicate destination is gone, but it is still not transparent why something is generated or not.

With the “not complete” part above is tells how the input looks like, but it doesn’t show how the output will look like. The branch examples also have only the branch-bundle example with one _index.md and a leaf bundle (subdirectory), but not _index.md, second.md, 3rd.md plus leaf bundle in a subdirectory like in my content directory.

It looks to me like it is either _index.md + subdirectories, or multiple .md files in a leaf directory. In the examples I can not see multiple .md files plus multiple leaf directories. At first look this looks like you can only do that and nothing else. And when I look how multiple input files in the same directory land as index.html in subdirectories, without an example of how the output will look like, I ask myself first if I did something wrong, and ask myself why is this happening.

I don’t even start to talk about headless bundles now… the example there is how to code it, but it is not an example about how to make sense out of it (at least I have the impression that I do not need to know ATM what it does in terms of my goal of converting from one templating engine to another).

All in all, it looks promising what can be done with hugo, but so far there is a lot of trial and error involved to make sense of it and to get it to work, and the debugging experience is frustrating. My experience so far is, that it looks easy on the outside (while reading the docs), but it isn’t, because there is an impedancy mismatch between my expectations of what is supposed to happen vs. what really happens. This means (for me), that the docs are written by someone who knows how hugo works, and knows all the invariants of the design of what hugo is supposed to achieve, but I haven’t found an explanation of this design and the invariants. For example why is thoutput ./name/index.html when the input is ./name.md (or in my case ./name.html). Can I change that to ./name.html? If not, why not? Hugo is doing some magic, without an explanation of the big picture of this magic. Or you can maybe tell the docs are more a reference guide for those which have seen hugo grow up, but it is not a documentation for people which are new to hugo, have seen other templating engines and come with expectations, and are not yet in the mindset of hugo. Converting something which exists and hoping to be able to produce the same output seems not possible with hugo, so it may have been a bad idea to try to do that as a first step into hugo.

If I compare that to the abandoned templating engine from which I want to convert away, I have to say that WML looked complicated and powerful, and it was complicated and powerful, but it told me what was wrong and where something was not ok, and what it did, and as such it was easy to follow and to find the issues (and easy things were much more easy than expected, but yes, complicated things wher complicated -> no mismatch of impedance).

If someone has read so far into my hopefully constructive explanation of issues with the docs of hugo: my problem at hand is not solved, but I’m at least some steps further. It looks like the only real solution to the issue will come by a lot of trial and error.

[alexandros]

There is a variety of issues in your project.

First of all in the project config you have the following:

disableKinds = [ "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT" ]

Basically you have disabled all list pages. You are outputting only regular pages.

–

Second in your homepage template you call a page.html partial that within contains just the following variable: {{ .Content }}

To render content on the homepage you need to range through the Regular Pages first. I do not see that in your homepage template, hence it renders empty.

–

Third to the point that is the root cause of the problem at hand.

As you have set up things right now the entire content folder is a single page.
index.en.html is that page. Everything else is an unpublished resource of this page.
index.de.html is a draft.
And everything under the directory x does not render on my end -even if you claim that http://localhost:1313/x/xhost.html is rendered I just do not see this happening.

–

This is the last time that I am writing the following in this forum -as I have written it more times than I care to remember-:

---

index.md or index.html or whatever extension ===> denotes a leaf bundle i.e. regular page, single page. Every other file within the same directory as an index.<whatever-extension> becomes a Resource of that page. To publish such a Resource one needs to use the methods mentioned in Page Resources

_index.md or _index.html ===> denotes a branch bundle. This is an optional file to enter meta data and extra content in list pages. Alongside this file, one can have other content files in the form of .html, .md or whatever or directories that are either other sections or leaf bundles.

---

You have come with a fixed set of expectations and strong opinions about how things should work in Hugo and what you expect from the software.

If you find what I wrote incomprehensible then Hugo is not for you. You would be better off using something else.