The announcement details a few things: Textile support is going to disappear, Markdown will only be implemented via Kramdown, and Pygments is disappearing and being replaced by the compatible (and faster) Rouge syntax highlighting.

Some of those changes have dates like “Starting May 1st, 2016, GitHub Pages will no longer support Textile”. Some things don’t have dates stated and are more aggressive: Starting immediately though, Pygments is not supported. If you use Github Pages, your next push will not deploy pages that use Pygments. The blog entry does not state explicitly that Rouge is not supported in Textile presently, so converting the Pygments sections to Rouge but staying in Textile is not going to leave you with polished pages - the Rouge sections will be unprocessed in the final HTML page. Again, that’s missing from the announcement.

Thus GHP users with articles in Textile that have Pygments code fragments to be highlighted, need to go to Markdown now, not on May 1st. You find out when you get an error email from GH, and you’re forced to go off immediately to bundle update your local Jekyll to see expanded error output that GH does not email to you. Maybe before you update Jekyll locally, do a local build copy the _site folder to somewhere safe for later comparison.

Pandoc for converting textile to markdown

As far as I can work out converting Textile to Markdown using Pandoc is far from perfect, not least of which is it is not expecting front-matter sections at all. Also Liquid/Jekyll/Rouge tags are not what it is expecting to process (or preserve).

Writing my own converter

It’s Python3 and up on Github. Feel free to use it. It does not do tables (I did my five by hand). It mangles links in some cases. It does nothing with textile’s inline style changes - e.g. you can make a single word red in a paragraph. You probably use different textile tags to subset I did.

To convert all your textile articles:

find . -name "*.textile" -exec python3 ../conv.py {} \;

This script is going to duplicate your .textile articles in .md ones. It does not do the Git operations. Interestingly Git thinks things are a rename (rather than add and delete) if the contents are 50% similar. Articles converted one by one seem to not confuse Git. Do and entire set, and Git begins to not believe there’s a mass-rename going on.

Other things missing from the GH blog posting

This advice would have been nice for _config.yml:

If your permalink design is like so:

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

You should change it to:

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

That trailing slash will stop you will getting a surprise .html suffix for your articles.

As with other changes, the Jekyll3 documentation is a better source for things that you’re going to want to know about this migration.

And the good news

Categories (and Tags) went back to mixed case. My top category “Trunk-Based Development” was original cased like that. Then there was a uniateral change to lower case “trunk based development”. Bugs were raised and debated. Now we’re back to the original case, although I don’t know when that happened, but I’m pleased.