Gitlab renders index.md files different than local hugo does

support
1

I’m building a personal hugo website and am deploying it via Gitlab pages. This worked pretty well so far, except for a strange bug I ran into recently:
I’ve changed my homepage from “_index.md” to “index.md” (topmost index file in the tree) in order to access pictures in sub-folders as page resources, which I wasn’t able to access with it named “_index.md”. This worked well building the page locally (using hugo 0.88.1), but as soon as I’ve uploaded these changes to Gitlab, my gitlab page became nearly empty (no content (where pictures were included), just header and footer).

I’ve played a while with gitlab-ci in order to track it down.
Resulting page as expected: Files · bd036ee1b5eee9481cda3673414dcaff8a2753da · Roy Meissner / rmeissn.gitlab.io · GitLab
Resulting page nearly empty: Files · e885460a88ae9b7e6f1356fcdcb90ac4a33c5351 · Roy Meissner / rmeissn.gitlab.io · GitLab
The second link is just one commit later, renaming “_index.md” to “index.md”. This won’t raise any CLI warning/error locally or on gitlab-ci.

Content of the nearly empty index.html from the gitlab build artifact:

<!doctype html><html lang=de-de><head>
<meta charset=utf-8>
<meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no">
<meta name=description content="Hompage of Roy Meissner">
<meta name=author content="Roy Meissner">
<title>Webseite über Roy Meissner</title>
<meta name=generator content="Hugo 0.88.1">
<noscript>
<link rel=stylesheet href=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/fontawesome.min.css defer>
<link rel=stylesheet href=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/solid.min.css defer>
<link rel=stylesheet href=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/brands.min.css defer>
<link rel=stylesheet href="https://fonts.googleapis.com/css?family=Montserrat:400,700" defer>
<link rel=stylesheet href="https://fonts.googleapis.com/css?family=Kaushan+Script" defer>
<link rel=stylesheet href="https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic,700italic" defer>
<link rel=stylesheet href="https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700" defer>
</noscript>
<link rel=stylesheet href=https://rmeissn.gitlab.io/css/vendor.min.ff6fc787c4ec5df9d28a94e2875fb22fbec3b8e1f62707323f7251d74ecfb34ff23e2b16eefbbd7847059cae69e514aaf398b178885f906e688ecbbb5b6a0e36.css integrity="sha512-/2/Hh8TsXfnSipTih1+yL77DuOH2JwcyP3JR107Ps0/yPisW7vu9eEcFnK5p5RSq85ixeIhfkG5ojsu7W2oONg==" media=screen>
<link rel=icon href=https://rmeissn.gitlab.io/favicon.png type=image/png>
</head>
<body id=page-top class=index>
<nav class="navbar navbar-expand-lg navbar-dark fixed-top" id=mainNav>
<div class=container>
<a class="navbar-brand page-scroll" href=https://rmeissn.gitlab.io/>Roy Meissner</a>
<button class=navbar-toggler type=button data-bs-toggle=collapse data-bs-target=#navbarResponsive aria-controls=navbarResponsive aria-expanded=false aria-label="Toggle navigation">
Menu <i class="fas fa-bars ms-1"></i>
</button>
<div class="collapse navbar-collapse" id=navbarResponsive>
<ul class="navbar-nav text-uppercase ms-auto py-4 py-lg-0">
<li class=nav-item>
<a class=nav-link href=#services>3 Säulen</a>
</li>
<li class=nav-item>
<a class=nav-link href=#portfolio>Portfolio</a>
</li>
<li class=nav-item>
<a class=nav-link href=#about>Über mich</a>
</li>
<li class=nav-item>
<a class=nav-link href=#clients>Institutionen</a>
</li>
<li class=nav-item>
<a class=nav-link href=#contact>Kontakt</a>
</li>
</ul>
</div>
</div>
</nav>
<div></div>
<footer class="footer py-4">
<div class=container>
<div class="row align-items-center">
<div class=col-lg-6>
<div class=social-buttons>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=mailto:roy-meissner@gmx.net target=_blank rel=noreferrer alt=E-Mail>
<i class="fas fa-envelope"></i>
</a>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=https://www.xing.com/profile/Roy_Meissner2 target=_blank rel=noreferrer alt=Xing>
<i class="fab fa-xing"></i>
</a>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=https://github.com/rmeissn target=_blank rel=noreferrer alt=Github>
<i class="fab fa-github"></i>
</a>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=https://gitlab.com/rmeissn target=_blank rel=noreferrer alt=Gitlab>
<i class="fab fa-gitlab"></i>
</a>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=https://stackoverflow.com/users/8404508/roy target=_blank rel=noreferrer alt=Stackoverflow>
<i class="fab fa-stack-overflow"></i>
</a>
<a class="btn btn-dark btn-social mx-2 hoverTransition" href=https://orcid.org/0000-0003-4193-8209 target=_blank rel=noreferrer alt=ORCiD>
<i class="fab fa-orcid"></i>
</a>
</div>
</div>
<div class="col-lg-6 text-lg-middle">
<a class="page-scroll hoverTransition" href=#page-top><i class="fa fa-arrow-up">&nbsp;Seitenanfang</i></a>
</div>
</div>
</div>
</footer>
<script type=text/javascript defer>let link,godefer;link=document.createElement('link'),link.rel='stylesheet',link.href='https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/fontawesome.min.css',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/solid.min.css',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/brands.min.css',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://fonts.googleapis.com/css?family=Montserrat:400,700',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://fonts.googleapis.com/css?family=Kaushan\u002bScript',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://fonts.googleapis.com/css?family=Droid\u002bSerif:400,700,400italic,700italic',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link),link=document.createElement('link'),link.rel='stylesheet',link.href='https://fonts.googleapis.com/css?family=Roboto\u002bSlab:400,100,300,700',link.type='text/css',godefer=document.getElementsByTagName('footer')[0],godefer.appendChild(link)</script>
<script src=https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/js/bootstrap.bundle.min.js></script>
<script src=https://rmeissn.gitlab.io/js/vendor.min.77bdf77320261d22ed734ff16f0e4368ddb1346535a15c8dcd76bae46e9e43d496530bf68e645dca6f8c68770fc60860409751afc32af88a01d6370dfed0658b.js integrity="sha512-d733cyAmHSLtc0/xbw5DaN2xNGU1oVyNzXa65G6eQ9SWUwv2jmRdym+MaHcPxghgQJdRr8Mq+IoB1jcN/tBliw=="></script>
<script src=https://rmeissn.gitlab.io/js/deferred.min.cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e.js integrity="sha512-z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==" defer></script>
</body>
</html>

Why is gitlab producing different results than hugo locally? I even tried downloading the docker image and executing the gitlab-ci commands within it… which gives me the expected results (a page full of content) for both commits.

2

As per your project’s .gitlab-ci.yml you are using the default Hugo version provided by Gitlab. However that is an old Hugo version, since their container registry has not been updated in 2 years. Not sure how you can use a more recent Hugo version for your project’s build, try searching their forums or perhaps someone else over here may know.

Also have a look (in case you haven’t) at the Page Bundles documentation.

In brief
_index.md is a branch bundle ruled by a list page template
index.md is a leaf bundle ruled by a single page template

1 Like
3

I’m using this image from their container registry, which provides hugo 0.88.1 as of the latest image (last entry of the list).
Downloading and executing the image also provides hugo 0.88.1.

@alexandros I’ve read the page bundle documentation and know I’m misusing it a little. Still, there shouldn’t be any difference between my local build to the gitlab-ci build, as it’s doing the exact same thing.

4

Yes, you are.

Your home page must be content/_index.md to avoid inconsistent results.

If I change content/_index.md to content/index.md:

  • Run repeatedly, this command renders the home page consistently using layouts/index.html.

    HUGO_NUMWORKERMULTIPLIER=1 hugo server  # No concurrency

  • Run repeatedly, this command renders the home page inconsistently using either layouts/index.html or layouts/_default/single.html.

    hugo server

If a process produces inconsistent results on one platform, I am not surprised if the results are inconsistent (or not) in a different way on another platform.

5

@jmooring Many thanks for digging into it and providing an answer to my question.

Even though this is largely my own fault, I feel like there should be some sort of warning printed to the terminal in case someone runs into the same behaviour. Is it correct at all to sometimes use “template A”, some other time “template B” to render something, even though this is not an intended use-case?

6

Is it correct at all to sometimes electrocute me, and other times not, if I choose to stick my finger in a light socket? Of course not. I should be electrocuted every time.

The homepage documentation seems pretty clear:

The homepage, similar to other list pages in Hugo, accepts content and front matter from an _index.md file. This file should live at the root of your content folder (i.e., content/_index.md).

There’s an open, somewhat related issue to emit warnings:
https://github.com/gohugoio/hugo/issues/8935

1 Like
7

I’m sorry, I didn’t wanted to offend you with my words.

Thanks for sharing the issue link! I’ve contributed there.