Look-up order of index.md

I’m puzzled if index.md is treated like a single page. The look-up order is defined in here. However, _index.md seems to be a special thing which evaluates to a list page. But what about index.md?

I get strange behaviour in the following minimal working example:

layout/_default/list.html
layout/_default/single.html
layout/foo/list.html
layout/foo/single.html

In case of the directory structure from above file content/foo/index.md is rendered as layout/_default/single.html. If rename content/foo/index.md to content/foo/_index.md then the file is rendered as layout/foo/list.html.

I must miss something and can’t help myself why one time the file is rendered via files in _default and the other time via files in foo. Any pointers?

I’m using hugo version 0.40.3

That’s exactly as designed :slight_smile:

The index.md and _index.md are special file names for leaf bundles and page bundles respectively.

See rows 2 and 5 of the table on this doc page:

The difference between the 2 page bundle types is a lot more than what you observed. I’d suggest reading the whole documentation above.

I’m still somewhat blind and do not get it :wink: I just read the mentioned section like a dozens of times but I do net get it.

Why is content/foo/index.md rendered via layout/_default/single.html and not via layout/foo/single.html?

In contrast content/foo/_index.md is rendered via layout/foo/list.html and not via layout/_default/list.html. I canot follow this behaviour.

Lets phrase my question differently. How can I define a different layout for a leaf page which should not be the default layout?

That concern is valid… the layout you think should be used, should actually be used. No, actually I misread your example… see my following comment.

Can you share the site repo?

The repo can be created as follows:

hugo new site test
mkdir test/content/foo test/layouts/foo test/layouts/_default
cat <<EOF > test/content/foo/index.md
---
title: test
---

test
EOF
cat <<EOF > test/layouts/foo/single.html
This comes from layouts/foo/single.html
EOF
cat <<EOF > test/layouts/_default/single.html
This comes from layouts/_default/single.html
EOF

If I then run hugo inside the test directory, the content of file public/foo/index.html looks as follows:

This comes from layouts/_default/single.html

Actually that works as expected… you need to visualize the whole “foo/index.md” as a single page… “foo” is not a section there… so the layout in foo/single.html does not apply there…

May be this example makes the concept clearer to you:

#!/usr/bin/env bash
# Time-stamp: <2018-05-13 14:32:18 kmodi>

rm -rf ./test
hugo new site test
mkdir -p ./test/{content/foo/leaf_bundle,layouts/{_default,foo}}
# Leaf bundle content
cat <<EOF > test/content/foo/leaf_bundle/index.md
---
title: leaf bundle test
---

leaf bundle test
EOF
# Regular page content
cat <<EOF > test/content/foo/regular_page.md
---
title: regular page test
---

regular page test
EOF

cat <<EOF > test/layouts/_default/single.html
This comes from layouts/_default/single.html
EOF

cat <<EOF > test/layouts/foo/single.html
This comes from layouts/foo/single.html
EOF

cd ./test || exit

echo ""
echo "Now visit http://localhost:12129/foo/leaf_bundle"
echo "and http://localhost:12129/foo/regular_page"
echo ""
hugo serve -p 12129

Uhh I think I get it now :smile:

Let me reflect on this in order to clarify that I really got it :wink:

If I want to come up with a side like https://example.com/foo/index.html which should be a leaf-page and the layout is different from everything else. Then I’m supposed to create a file content/foo/_index.md which in the end uses a list template although this page has nothing in common with a list and is actually just a single page but we cannot use a single page because foo is not a section.

Sorry for asking such stupid questions but I’m new to hugo and this took me the whole weekend :flushed:
I will leave it for today and take some rest

… then use a custom type and/or layout front-matter. Leaf vs branch bundle is not used to pick a different layout kind; selecting one of those should depend on you content organization requirements.