How to generate /section/index.html for all sections?

support
1

Hello,

I’m new to Hugo but not to SSGs. I have been pulling out my hair trying to get Hugo to generate an index.html under each section in /public/ and I would really appreciate some feedback.

Scenario: I have a Hugo-based documentation website with several pages organized by section (/content/section1, /content/section2, etc.). I want users to be able to click the section name in a breadcrumb navigation and have it load an index page at /public/section/index.html which lists all of the pages under that particular section. I have a full ToC on the homepage, and the navbar is generating the breadcrumb as expected, but without the index.html files, the links are 404.

Thus far, I’ve created the following templates and files without effect:

/themes/theme/layouts/_default/list.html
/themes/theme/layouts/_default/section.html
/themes/theme/layouts/section/index.html
/content/section1/_index.md
/content/section2/index.md

Regardless of what I do, Hugo will not generate an index.html page under any of the section directories in /public.

This seems like such an easy thing to accomplish, but I just can’t figure it out. I do see that section indexes are generated in the root of /public (/public/section1.html, /public/section2.html, etc.), but that’s not what I want.

I’d appreciate any feedback you can provide.

Cheers

2

Please provide a demo repo with a project showing what’s happening, and then describe what you expect. :slight_smile:

3

@maiki

Thanks for the reply, but like I said this has already been identified as an existing issue (4428). Expected behaviour is that /content/section/_index.md should generate /public/section/index.html, but when uglyurls = true it generates /public/section.html instead. This leaves /public/section/ without a directory index, which is not the traditional expectation of directory indexes regardless of pretty URLs.

4

I’m trying to figure out why that is your expected behavior. In the docs part of the example for rendering with the uglyURLs option is:

└── content
    └── about
    |   └── _index.md  // <- https://example.com/about.html

Whereas sans uglyURLs (default), /content/section/_index.md generates /public/section/index.html. That’s what you want, it appears.

Listen, if you are okay with this having found a two year old bug report, I’m good. Please mark your message as the solution. :slight_smile:

5

I think it finally clicked: you want most pages to resolve to filename.html, but not section list pages, which themselves take on the name of the the section.

This is why I asked for a demo repo, and why someone should put it together with real world examples and add it to that issue. I suspect hardly any of the regulars around here use uglyURLs, so how it is supposed to behave looks mostly correct from our POV. And when you ask, “how do I generate an index.html?” I wonder why you are using uglyURLs at all, since by default all of them are index pages…

6

No problem. If you review the bug thread I’ve linked to, you’ll see that the Hugo documentation was updated immediately after the bug was discovered, but the debate continued as to whether this was appropriate behaviour as it is unconventional. Personally, it does seem odd that Hugo will not allow developers to generate an index.html inside a sub-directory if uglyurls = true.

The ticket remains open to implement an option which supports the original (expected) behaviour that was present in Hugo until sometime between versions 0.21 and 0.54, as well as the behaviour that was inadvertently adopted sometime later (so as to not break existing websites).

7

For what it’s worth, I’m using ugly URLs because this website will be served from a local filesystem (unhosted) and pretty URLs won’t work in such a case (e.g. you must link to the HTML file itself).

8

So this appears to be a side effect of uglyurls = true. When uglyurls is true, section pages are generated in the root directory of /public instead of their relative section folders. There is an open ticket to resolve this here:

Workaround: As TjeuKayim mentions in the above bug thread, a workaround is to name the _index.md something else (e.g. dirlist.md) and add slug: index to the front matter of the file. This will generate index.md in the expected section’s directory. Depending on your theme’s design, you might need to add layout: section to the front matter as well to avoid it using the single.html template.

For example:

  1. Rename /content/some-section/_index.md to /content/some-section/dirlist.md
  2. Add slug: index and layout: section to the front matter of the file
  3. You’ll also need to ensure permalinks are configured to use :slug for the affected content files
  4. Hugo will now generate /public/some-section/index.html using the section.html layout template as expected
9

No, I simply want one index.html rendered as a section list in every sub-directory containing content pages, regardless of whether uglyurls is true. This currently isn’t possible. For example, I want /public to render as follows:

└── /public
    └── /section1
    |   └── article1.html
    |   └── index.html   <- section template listing all pages under section1
    |   └── some-other-article.html
    └── /section2
    |   └── article1.html
    |   └── article2.html
    |   └── article3.html
    |   └── index.html   <- section template listing all pages under section2
10

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.