It is better to have index.html or index.md?

Help
1

This Beautiful Jekyll theme has an index.html file, yet it seems this should be index.md.

  1. It actually includes Markdown that gets preprocessed
  2. md is the more typically used file extension
  3. If I rename it to index.md, Jekyll works except for the warning: “Pagination: Pagination is enabled, but I couldn’t find an index.html page to use as the pagination template. Skipping pagination.”

Is index.html or index.md preferable?

1 Like
2

I’m not sure there is a correct answer for “what is better” because it seems that .html and .md extensions are pretty much interchangeable in Jekyll. So my latest rule of thumb is if file is mostly Hyper Text Markup Language I use the .html filename extension. If the file is mostly Kramdown (read Markdown Language) then I use the .md filename extension.

At the end of the day, I think it just boils down to personal perference.

2 Likes
3

@pippim @JoshuaFox The choice shouldn’t be made on if mostly….
Instead, it should be made on whether the file needs to be converted or not.

If a file is 99% HTML and 1% Markdown, and the extension is .html, the 1% Markdown remains unconverted in _site/index.html. But if the extension is .md (or any another valid Markdown extension), then resulting _site/index.html will be 100% HTML.

4

@ashmaroli I thought I read some where that it is converted when file starts with ---. For example, the first four lines of my index file contains:

---
title: Welcome to Pippim
layout: default
---

And that I believe is what causes Jekyll to convert Kramdown to HTML.

It will be interesting for others in the community to share their understanding…

5

the front matter dashes mean jekyll will process it - not necessarily markdown.

If you have markdown the file needs to be a md file I think. An html file is html - so I don’t think looking for markdown in there would make sense.

html can be in an html file or a markdown file though.

in the file above that is linked - I don’t see any content in the actual index.html file other than the front matter. It must be coming from the layout. In that particular case I think that file could be md or html - all it has is front matter - but no actual page content.

6

I see that my earlier comment is not clear on the intent.

What i mean to convey is that, if a file contains 1% Markdown and 99% HTML and you want the 1% Markdown to converted into HTML as well, then the file extension should be a valid Markdown extension.

Jekyll’s converters are determined by file extension not by file content:

  • default Markdown converter, kramdown, acts only on Markdown files.
  • the built-in sass converter acts only on .scss and .sass files, etc

The presence of front matter dashes determine whether a given file needs to be processed by Jekyll. The exception to this rule is documents inside _posts folder for compatibility with legacy projects.

2 Likes