Jekyll and S3 permalink problems? Here's how to fix it

I recently debugged an issue with permalinks generated by Jekyll and deployed on Amazon S3 with s3_website. The problem I encountered was that all of the permalinks for my blog posts worked perfectly fine when testing locally through http://127.0.0.1:4000 when running jekyll serve. All the posts were served locally as http://127.0.0.1:4000/post-name (rather than being served with an extension, like http://127.0.0.1:4000/post-name.html). However, the same permalinks didn’t work once I had them deployed on AWS using s3_website push. I had files of the form post-name.html in my S3 bucket, but they were being referenced as post-name (without the .html extension) from the main page index.html.

After looking into the code generated by jekyll build and what s3_website push uploaded to AWS, this turned out to be a trivial configuration change in _config.yml. I had been generating permalinks for blog posts like this:

permalink:      /:year-:month-:day/:title

The simple fix was to make sure to have a trailing slash:

permalink:      /:year-:month-:day/:title/

It also works to explicitly force an .html extension for all pages both locally and on S3, but the URL formatting isn’t as nice:

permalink:      /:year-:month-:day/:title:output_ext