Over a million developers have joined DZone.

Because GitHub Decided I Had to: Convert From Textile to Markdown

DZone's Guide to

Because GitHub Decided I Had to: Convert From Textile to Markdown

With GitHub now running Jekyll 3.0, the Ruby-based, static site generator, author Paul Hammant takes us through some helpful lessons and gotchas to watch out for in order to make the conversion easier.

· Web Dev Zone ·
Free Resource

Learn how Crafter’s Git-based content management system is reinventing modern digital experiences.

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 an 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 while 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 during this migration.

And, the Good News

Categories (and Tags) went back to mixed case. My top category “Trunk Based Development” was originally cased like that. Then there was a unilateral 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.

Crafter CMS is a modern Git-based platform for building innovative websites and content-rich digital experiences. Download this white paper now.

jekyll ,static site ,github ,converter ,markdown

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}