Search code examples
githubjekyllgithub-pages

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

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

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, ...