Tell Jekyll (on github pages) to convert README.md to README.html, not index.html

github, github-pages, jekyll

Solution

You can use a permalink in `README.md`:

---
permalink: README.html
---

TypeTheory: the mathematical study of type theories, in univalent foundations
==========

Code  on C-systems, D-systems, ...

You may also use front matter defaults in your `_config.yml`:

defaults:
  - 
    scope:
      path: "README.md"
    values:
      permalink: "README.html"

But you will still need a front matter in `README.md` to make it parsed by jekyll (even if it is an empty one):

---
---

TypeTheory: the mathematical study of type theories, in univalent foundations
==========

Code  on C-systems, D-systems, ...

Problem

I am using Jekyll to build a project webpage, on Github Pages, using the “Dinky” theme, straight out of the box. The `README.md` gets automatically converted to `index.html`, which is very helpful for quickly getting started. However, I would like to have a separately-written main page `index.md`, and instead convert `README.md` to `README.html` (as it does with most `*.md` files). When I add my `index.md`, Jekyll converts it to `index.html` as hoped, but now gives no conversion at all of `README.md` — presumably it has `index.html` as the target for both `README.md` and `index.md`, and the latter wins. How do I tell Jekyll to go back to using `README.html` as its conversion target for `README.md`? Preferably, I would like a solution that doesn’t require adding config data in `README.md` itself, so that I can continue to keep `README.md` in sync with the human-readable version in the `master` branch. Note for reproducing it: all this occurs both when built online through Github Pages, and with a local `jekyll build`. The only custom jekyll settings I am using are `gem 'github-pages', group: :jekyll_plugins` in the site’s `Gemfile`, and `theme: jekyll-theme-dinky` in the site’s `_config.yml`. It seems to be specific to the Github Pages themes, but not to the Dinky theme: other themes beside Dinky exhibit the same behaviour, but a bare Jekyll site does not seem to. Edit: thanks to @wasthishelpful for a very helpful comment and partial answer. Adding a YAML frontmatter block to `README.md` setting `permalink: README.html` does what I was looking for. Unfortunately I’m still not finding a way to achieve the same effect just by modifying `_config.yml`: e.g. adding a frontmatter default there ``` defaults: - scope: path: "README.md" values: permalink: "README.html" ``` doesn’t seem to have any effect. (I’ve tried both with and without the quote marks around the filenames, and both before and after the line `theme: jekyll-theme-dinky`.)

Original source