How to remove extension on pages with dots (periods) in the name

I’m having an issue described in application/octet-stream content-type return when post permalink doesn't end with .html · Issue #4996 · jekyll/jekyll · GitHub (but comments are disabled there)

I’m using GitHub Pages and trying to preserve URLs after migrating my site from Atlassian Confluence (all pages had no extension or trailing slash)

I’ll summarize the issue here:

  • I can set permalink: /path/Page+Title in front matter, and then Jekyll will allow the url without .html (it generates a file with .html extension that can be accessed without it) This is good
  • If the permalink URL has dots in it, eg /path/Release1.2.3, then the generated file does not have a .html extension, and is served with Content-Type: application/octet-stream This is bad
  • If I add a trailing slash to the permalink on pages with dots, then:
    • A directory structure is generated: Release1.2.3/index.html
    • The URL redirects to add a trailing slash This is slightly bad, but tolerable
    • All relative links break: [....](Sibling_Page) is now Release1.2.3/Sibling_Page This is bad

Is there a better approach that does not mess up link URLs in every page with dots in the name? Is there a way to convince Jekyll to generate a .html page for markdown files with dots?

This issue discusses using a custom converter, but it’s unclear whether this would work with GitHub Pages.

Versions: GitHub supported versions (Jekyll 3.9.0, Minima theme 2.5.1)


I have an ugly but working workaround:

  • Changed all front matter permalink: items to end in .html
  • Removed .html in the nav template (minima, in my case):
<a class="page-link" href="{{ my_page.url | relative_url | remove : '.html' }}">{{ my_page.title | escape }}</a>

Now nav and normal links seem to work fine:

[Sibling Page](Sibling+Page)

Any page is accessible via NAME or NAME.html, but there are no links to .html

I’d say this approach is fine

Jekyll can do this for you by setting in the config.

permalink: pretty

This is useful in other situations like if you have


And this will use the pretty format for you I links, so you can switch the config value in one place and not have to worry about the rest of the site

href="{{ my_page.url }}"

"/my-dir/" <!-- if format is pretty -->

"/my-dir.html" <!-- if you left the default format -->

As it avoids this default where the directory appears to be a standalone page and also a dir which feels weird.


And also if you edit the page of /my-dir/abc.html in your browser to be /my-dir/, that will appear as a 404 and is bad experience for the user.