Preserve URL Extensions with Jekyll

jekyll 10 comments suggest edit

In my last post I wrote about migrating my blog to Jekyll and GitHub Pages. Travis Illig, a long time Subtext user asked me the following question:

The only thing I haven’t really figured out is how to nicely handle the redirect from old URLs (/archive/blah/something.aspx) to the new ones without extensions (/archive/blah/something/). I’ve seen some meta redirect stuff combined with JavaScript but… UGH.

UGH Indeed! I decided not to bother with changing my existing URLs to be extensionless. Instead, I focused on preserving my existing permalinks by structuring my posts such that they preserved their existing URLs.

How did I do this? My old URLs have an ASP.NET .aspx extension. Surely, GitHub Pages won’t serve up ASPX files. This is true. But what it will serve up is a folder that just happens to have a name that ends with “.aspx”.

The trick is in how I named the markdown files for my old posts. For example, check out a recent post: 2013-11-20-declare-dont-tell.aspx.markdown

Jekyll takes the part after the date and before the .markdown extension and uses that as the post’s URL slug. In this case, the “slug” is declare-dont-tell.aspx.

The way it handles extensionless URLs is to create a folder with the slug name (in this case a folder named declare-dont-tell.aspx) and creates the blog post as a file named index.html in that folder. Simple.

Thus the URL for that blog post is But here’s the beautiful part. GitHub Pages doesn’t require that trailing slash. So if you make a request for, everything still works! GitHub simply redirects you to the version with the trailing slash.

Meanwhile, all my new posts from this point on will have a nice clean extensionless slug without breaking any permalinks for my old posts.

Found a typo or error? Suggest an edit! If accepted, your contribution is listed automatically here.



10 responses

  1. Avatar for khalidabuhakmeh
    khalidabuhakmeh December 3rd, 2013

    That's pretty cool, congrats on the new blog.

  2. Avatar for Abdalaziz
    Abdalaziz December 4th, 2013

    When I click on "Edit" to do a pull request, I get a 404 error.

  3. Avatar for Orry Rotem
    Orry Rotem December 5th, 2013

    FYI It seems to work when already logged on GH

  4. Avatar for petevb
    petevb December 5th, 2013

    There's a link on to your article:

    But that's 404. I found the real article in your archives at:

    That article contains a link to:

    Again 404, and actually at:

    Is what seems to be an off by one a result of this migration?
    Cheers, Pete

  5. Avatar for haacked
    haacked December 5th, 2013

    Yeah, I think I had quite a few of those unfortunately. I just realized my script to check this situation was not correct. Thanks for the reports!

  6. Avatar for petevb
    petevb December 6th, 2013

    No worries - thanks for the blog!

  7. Avatar for Alistair Lattimore
    Alistair Lattimore December 8th, 2013


    If you're goal was to not worry about hosting and so forth, what made you choose GitHub Pages over say and using a custom domain?

    I'm imagining a scenario in the future where you might want to customise your blog in some way and GitHub Pages is going to make that difficult. If you went to initially but later decided that you wanted to self-host WordPress for increased customisation - it'd be an easy exercise.

    Interested to hear your decision making process on it.


  8. Avatar for haacked
    haacked December 8th, 2013

    I like that people can send pull requests now to my blog posts should they want and everything is hosted in Git.

    And if I needed a customization not supported by GitHub Pages, I _always_ have the option to just use Jekyll plugins on my local machine and push the generated output to GitHub pages. That's the Octopress approach.

  9. Avatar for Alistair Lattimore
    Alistair Lattimore December 12th, 2013

    Thanks for replying.
    Just curious about your logic.

  10. Avatar for Eric Duncan
    Eric Duncan April 4th, 2014

    I'm in the .middle of converting my old CommunityServer blog and this is a nice trick for the .aspx.

    I wanted to comment on the option for people submitting pull requests for ur pages. I think that won't be possible.

    It may be the way my GitHub Pages and Octopress works with PoshGit which that in and of itself is a problem:


    ^- temp URL until I convert. But the post is valid and Google may find me now that I post this, doh.

    When setup like this, I cannot issue a:

    [source]> git pull origin source

    It does the funky thing of merging in changes I already pushed up and creates another commit for now a double commit.

    Yes, you can do this from the _deploy folder that is on the [master] branch as that is what the Ruby script does (as outlined in that post).

    Maybe I missed a haack of my haacked setup for my Hacker blog of Octopress? :-)