Index.html/index.md is absolutely required?


#1

Hi,

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 jekyllrb.com.

What particularly interested me is ‘index.html/index.md’ 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 home.md/html. I checked why they open home.md/html and not index file. Those home.md/html 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 home.md/html because of permalink?

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

thanks.


#2

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.

Examples:
<root>/your-page.md ~> _site/your-page.html
<root>/your-page-2/index.md ~> _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/home.md 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/about.md and it’ll build out at _site/about/index.html


#3

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 home.md 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).


#4

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


#5

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