Page bundle functionality breaking use of index.md?

support
1

I have a website which has been running fine on on Hugo (and I am a big fan of Hugo!) up to version v. 0.26. This site was migrated from a website which has been in continuous operation for ~20 years, so includes a variety of arrangements of content. A common pattern is to have a directory which includes an ‘index.md’ file as well as other pages, further subdirectories also including index.md files etc. I have also been making use of the _index.md functionality in sections.

All of this works fine in Hugo v.0.26

Having just tried to upgrade to Hugo v0.32.3, I have found that much of the site is no longer rendered.

I have identified a couple of patterns where things are broken, but I cannot make sense of these according to the release notes for the versions of Hugo since v.0.26

Pattern A

Source tree

content
├── conference
│   └── 2018
│       ├── committees.md
│       ├── index.md
│       ├── location.md
│       ├── submissions.md
│       ├── travel.md
│       └── venue.md

Resulting output tree

webroot
├── conference
│   ├── 2018
│   │   └── index.html
│   └── index.xml

In this pattern, the index.md file is rendered correctly, but none of the other *.md files are rendered.

Pattern B

Source tree

content
│── usage
│   ├── decisions
│   │   ├── 2000
│   │   │   ├── 2dc2.md
│   │   │   ├── 2dcq1.md
│   │   │   ├── 2dcq3.md
│   │   │   ├── 2dcq4.md
│   │   │   ├── 2dcq5.md
│   │   │   ├── 2dcq6.md
│   │   │   ├── ballotinfo.md
│   │   │   ├── contrib-creator-publisher-agents-index.md
│   │   │   ├── coverage-20000401-results.md
│   │   │   ├── coverage-20000401-settings.md
│   │   │   ├── coverage-index.md
│   │   │   ├── coverage-log.md
│   │   │   ├── coverage-results.md
│   │   │   ├── coverage-settings.md
│   │   │   ├── coverage-voters.md
│   │   │   ├── creator-contrib-publisher-20000401-index.md
│   │   │   ├── creator-contrib-publisher-20000401-log.md
│   │   │   ├── creator-contrib-publisher-20000401-settings.md
│   │   │   ├── css
│   │   │   │   └── dcmi-wd.css
│   │   │   ├── date-20000401-index.md
│   │   │   ├── date-final.md
│   │   │   ├── date-index.md
│   │   │   ├── date-log.md
│   │   │   ├── date-observers.md
│   │   │   ├── date-voters.md
│   │   │   ├── dcsubdesc-final.md
│   │   │   ├── dct1-20000401-results.md
│   │   │   ├── dct1-20000401-settings.md
│   │   │   ├── dct1.md
│   │   │   ├── descript-format-identifier-lang-20000401-index.md
│   │   │   ├── format-extent-qual.md
│   │   │   ├── format-imt-qual.md
│   │   │   ├── format-medium-qual.md
│   │   │   ├── images
│   │   │   │   ├── dcmi_22.gif
│   │   │   │   └── piros.gif
│   │   │   ├── index.md
│   │   │   ├── relation-20000401-index.md
│   │   │   ├── relation-20000401-log.md
│   │   │   ├── relation-20000401-settings.md
│   │   │   ├── relation-index.md
│   │   │   ├── relation-log.md
│   │   │   ├── rfc2396.txt
│   │   │   ├── subject-title-type-20000401-index.md
│   │   │   ├── subject-title-type-20000401-log.md

Resulting output tree

webroot
├── usage
│   ├── decisions
│   │   ├── 2000
│   │   │   ├── css
│   │   │   │   └── dcmi-wd.css
│   │   │   ├── images
│   │   │   │   ├── dcmi_22.gif
│   │   │   │   └── piros.gif
│   │   │   └── rfc2396.txt

In this pattern, not even the index.md file is rendered, but some images and a *.txt file are rendered.

It seems to me that this is a result of the page bundling function, which I do not want or need.

Is there a way to switch this off?

Thanks!

2

See this thread for a workaround that another user did for this same issue: https://discourse.gohugo.io/t/solved-site-no-longer-builds-with-version-0-32-theme-hugo-foundation6/9944/6

As a side note the use of index.md has not been a recommended method for a while now and since Hugo 0.32+ using it converts a content folder into a Page Bundle with.Resources.

3

Thanks @alexandros. I did see the workaround you’ve linked to here.

Is there a recommendation for what to use to to simply have an ‘index’ page (in the general sense) for any folder? This would seem to be a very common requirement.

Using the workaround suggested - the only way I can see to get this to work is to rename the index.md file as suggested (e.g. home.md) and then add into the frontmatter for that page something like:

slug: "."

so that /folder/home.md will render to /folder/

But this feels like a hack :frowning:

Any further thoughts on this? I have a major website (4.5K pages). Wholesale renaming of pages is non-trivial, but I’m prepared to do this if I can be confident that change will be somewhat future-proof.

Thanks for your assistance!

4

Page Bundles are future proof, because using them enables Image Processing for .Resources.

5

Apologies - I am really struggling to understand now :frowning:

If I want to serve a site with content like this:

content
├── conference
│   └── 2018
│       ├── committees.md
│       ├── index.md
│       ├── location.md
│       ├── submissions.md
│       ├── travel.md
│       └── venue.md

where these two URLs work:

/conference/2018/
/conference/2018/travel/

how should I arrange the content?

I don’t mind using new functionality to do this, I just can’t see how to do what seems to me to be a very simple thing.

Clearly I am misunderstanding something…

6

To have the following URLs

You organize your content like this.

   content
    ├── conference
    │   └── 2018
    │       ├── committees.md
    │       ├── _index.md
    │       ├── location.md
    │       ├── submissions.md
    │       ├── travel
    │       │   └──index.md
    │       └── venue.md

travel.md becomes /travel/index.md (a Page Bundle)
index.md becomes _index.md to enable the Nested Section /conference/2018/

Nested Sections need _index.md to be enabled. These can also have image resources next to them.

EDIT
And that is if you need additional .Resources under /conference/2018/travel/ if that URL is meant to be a simple content file like the rest in the 2018 directory you simply leave it as it is.

7

Thanks @alexandros!

OK - I’m starting to understand. Changing the index.md to _index.md means that this content:

content
├── conference
│   └── 2018
│       ├── committees.md
│       ├── _index.md
│       ├── location.md
│       ├── submissions.md
│       ├── travel.md
│       └── venue.md

allows these two URLs to work

/conference/2018/
/conference/2018/travel/

Where I have content nested more deeply, if I’ve understood correctly, then what I need to do is to change any index.md files I find into _index.md, except where these are ‘leaves’ (i.e. at the end of that particular branch of the tree).

Does that sound right?

8

Yes that sounds alright.

9

We have just preformed a fairly complicated search and replace on index.md files, renaming some to _index.md as appropriate, and we appear to have a functioning website once more.

@alexandros - thanks very much for your help with this!