Skip to content

Spike: Investigate impact of renaming index files

Hugo requires index files to be named _index.md rather than index.md (docs). See also: https://discourse.gohugo.io/t/cant-figure-out-the-very-basics-of-content-structure-generated/14891/13

If you do not rename index files, the build contains fewer pages.

We currently do this renaming as part of the build process here.

However, this won't work long-term:

  • the file rename would show as a diff for people working on docs with a local site running, but we wouldn't actually want it committed back to the source docs
  • links to index.md pages don't work

So, we will probably need to do a permanent renaming of these files, rather than modifying them at build-time.

We need to check:

  • How does that affect /help, if at all? Do we need to adjust /help to render _index.md files as it would a regular index page?
  • How can we enforce using _index.md rather than index.md for new pages? This is unconventional, so we will probably need to test for it.
Edited by Sarah German