GitHub Pages: can I use a mix of html and md files?

In the past, I’ve used GitHub pages to ether:

  • host simple client-side web pages
    OR
  • host .md files and have jekyll automatically convert them to .html

It seems like I don’t have to configure anything differently for those two cases; it just works.

However, now I would like to do both in one project - I am hosting an HTML JS CSS “web app” of sorts (from the root folder of the master branch of the project), and I’d also be able to access the README.md file as HTML on the github. io page.

But it seems like Jekyll just ignores the .md files if there’s already an index.html - is that correct? or did I just screw up some settings? I tried adding some default things to _config.yml but it seems to make no difference.

The repository in question is [redacted because I can only put two links in one post and you can deduce it from the others]

I can visit https://yanamal.github.io/DocPrompter/README.md and it shows a plain-text representation of the markdown file, but https://yanamal.github.io/DocPrompter/README.html is a 404

Thanks!

1 Like

The problem turned out to be much simpler than I thought. Through experimentation, I found that jekyll seems to just exclude README.md specifically from the pages it turns into HTML.

So I ended up creating a separate .md file and just using the following line to include the contents of README.md in it:

{% include_relative README.md %}
2 Likes