Page bundle classification using filenames other than index.md

support
1

TL;DR:

I want to see how I can create page bundles without naming my pages index.md or _index.md. For example, using README.md to align with displaying the pages on Git hosting site web interface (Github, Gitlab, etc.)

Longer version:

I am moving my knowledge base to Hugo. It’s basically a Git repo where I write things in markdown and the index for each directory is README.md (shows up when users navigate to that directory in the web interface). You can see the original one here: https://github.com/parsiya/Parsia-Clone

Updating the index takes a lot of time so I am migrating it to Hugo. I have modified my own theme for now. You can see a test version of the repo based on clone-2 branch: http://clone-test-bucket.s3-website-us-east-1.amazonaws.com/

The idea is that I can create a directory for each new entry, add the category, tags and summary in frontmatter and just publish it without needing to care about the index. The page bundle feature works perfectly for this because I can have all resources in the same path.

Problem is I need to name my files index.md instead of readme.md and this means they will not show up on Github or Gitlab when users navigate to the directory. While it’s not a must, it’s a nice to have so people can browse the repository too.

Looking at the source, it seems like index. / _index. are hardcoded in:

// Returns the given file's name's bundle type and whether it is a content
// file or not.
func classifyBundledFile(name string) (bundleDirType, bool) {
	if !isContentFile(name) {
		return bundleNot, false
	}
	if strings.HasPrefix(name, "_index.") {
		return bundleBranch, true
	}

	if strings.HasPrefix(name, "index.") {
		return bundleLeaf, true
	}

	return bundleNot, true
}

Now I can do several things:

  1. Rename every README.md to index.md before creating the Hugo website and then renaming them back after that before commit. This works for the most part but the Git link on top of every page will have to manually change the file name too. I am not sure how well that will work for CI because at the moment I do everything locally with some batch files.

  2. Build a custom version of Hugo and add readme.md.

What do you think? Is there a better way?

2

You cannot, as they are the very core of branch vs leaf bundle definitions.

Just my opinion – Is it really worth that? Why not just point your repo visitors to your repo Website? I do that for my repos.

3

Thanks for the reply.

You are right, it’s in the “nice to have” territory. I am actually curious to see if I can make something like that work. Will post a solution if found here in case someone else wants to do the same.

4

So the rules are. To be a bundle it has to be a content file and have a base filename of either “_index” or “index”.

README.md.etc are not supported. There may come a frontmatter config for this, but that is a big maybe and it is not on my list.

5

Thanks Bep. I rebuilt Hugo with readme detection and it worked for the most part. However, I decided to go the other way and just stick to index.md.

6

If you are building and deploying your site using a service like Netlify, you can do the renaming of README to index in a more efficient way …

  1. Commit the files named as README.md as GitHub would like it.
  2. Normally the “command” parameter of Netlify can be just “hugo”, but this will change a bit for you. This goes in the netlify.toml in your repo root.
  3. Create a little bash script that loops through your repo files, and renames README.md to index.md or _index.md as appropriate. I believe just 2 lines of find .. -exec .. mv commands should do this. Test this script and commit it to your repo root. But don’t commit the renamed files.
  4. Now modify the “command” in your netlify.toml to "./readme_to_index.sh; hugo".

That’s it. This way, you then no longer need to do the renaming manually… the script will do that instead just before hugo builds the site on Netlify.

7

Hi @kaushalmodi, I appreciate the detailed response.

I decided to take the lazy route, I am adding the README.md but ignoring them in the config file so they are not rendered. Everything else happens in index.md or _index.md.

Thanks a lot