Index.html/ is absolutely required?


I’ve been learning and building my website using Jekyll hosting at Github (and another hosting place).

So far I’m getting a better handle on how Jekyll work. I check out other person’s theme and learn how they “connect the dot” between one page to another. And I checked out the documentation/guide/tutorial on

What particularly interested me is ‘index.html/’ file. When I check out other people’s Theme, I tend to trace their website (to see how it is connected from one page to another and etc). I noticed that some of thier website doesn’t have index file at their rootpath. I’m puzzled by that. I noticed that it open I checked why they open and not index file. Those has permalink set to ‘/’.

My question is. Is index.html/md absolutely required at rootpath? If so, then how other people’s didn’t have it at rootpath but still open because of permalink?

What happen if there is no index file. And what is the requirement?


1 Like

It comes down to your preference. Jekyll is flexible enough to organize your pages how you want.

If you want the most hands-off approach you place a page (.md or .html) wherever you want and Jekyll will build it in the same exact location.

<root>/ ~> _site/your-page.html
<root>/your-page-2/ ~> _site/your-page-2/index.html

Some people don’t like to litter their root folder with pages and instead like to group them in a folder simliar to how _posts work. A common practice is to use _pages (don’t forget to include it in your _config.yml) and the assign permalinks to each to tell Jekyll were to build the .html.

This obviously takes more effort since you need to add permalink to the front matter. But I think this is the method you see where someone has _pages/ and it builds to _site/index.html

By setting permalink: / in its front matter it achieves this.

You could also do something like:

permalink: /about/

In <root>/_pages/ and it’ll build out at _site/about/index.html

1 Like

Ahh…Your explanation is a big help. It really clear up the confusion. It is all about what the end result (_site) not what’s the file/folder’s structure before the build.

Now what will happen if you have index.html/md in root folder AND with "permalink: / " front matter. That will produce two index.html?

I was under the impression after reading documentation that index.html must be in root folder without any emphasize on 'end result (_site).

You’ll only get one… whatever file Jekyll reads last will overwrite the one before it.

And index.html only needs to be in the root when you’re using pagination. That plugin is extremely picky about file placement.

1 Like