A look behind our decision to standardize on a single Markdown engine for GitHub Pages

Two months ago, we announced that GitHub Pages is dropping support for the RDiscount, Redcarpet, and RedCloth (Textile) markup engines on May 1st. For the vast majority of users, this should be an easy transition, as kramdown supports all of RDiscount and Redcarpet’s most popular features, and if you’re making the transition from Textile, @jldec’s post last month should walk you through the process.

With the May 1st sunset quickly approaching, we wanted to take a few moments to take a look at the numbers and the discussion behind our decision to drop support for the non-kramdown markup engines within GitHub Pages:

Web publishing has come a long way since the Jekyll project began some eight years ago. Today, Markdown is largely the lingua franca of the open source community, but that doesn’t mean that certain regional dialects haven’t emerged over the years, as each markdown engine adopted a slightly different interpretation of how they thought Markdown should work. As Markdown engines diverged, so too did the experience of authoring content on GitHub Pages and authoring content elsewhere on GitHub.com such as in comments and READMEs.

One of our historic design philosophies at GitHub is that “anything added dilutes everything else“. While being able to fine tune the pipeline that’s used to render your content may be helpful in some unique cases, for the vast majority of users, that added complexity is one more thing that you’ll have to learn, one more decision that you’ll have to make, and ultimately that option serves to heighten the learning curve for new users.

Today, GitHub Pages is home to just over one million distinct sites, with thousands more being added each day. On an average day, we’ll process upwards of 50,000 builds, and of those 50,000 builds, more than 40,000 either don’t ask for a specific Markdown engine, or ask us to use kramdown, the default. That means that when we look at markup rendering across GitHub Pages, Redcarpet accounts for just shy of 2% of all builds, RDiscount accounts for about half a percent, and Textile accounts for one-tenth of one percent.

In standardizing on a single Markdown engine, we are able to improve the publishing experience for the vast majority of GitHub Pages users. Not only are we able to remove the complexity and confusion associated with new users being forced to distinguish between multiple markup engines or reading documentation for the incorrect interpreter, we are able to bring the experience of authoring Markdown content on GitHub Pages more closely in line with the experience you’ve come to expect when using Markdown anywhere else on GitHub.

If you’re still using RDiscount, Redcarpet, or RedCloth, next time you push to your GitHub Pages site, you will receive an email from us with instructions on how to upgrade. We highly recommend you test building your site with kramdown prior to the May 1st deadline. If you’re a GitHub Enterprise user, this change will affect GitHub Enterprise versions 2.7 and later.

In most cases, upgrading to kramdown should be a matter of updating your site’s configuration. If in the off chance you do run into any trouble, please get in touch with us, or if you have questions about what this change means for your GitHub Enterprise appliance, please contact GitHub Enterprise support. We’re here to help.