Most people use Jekyll with Markdown as a converter, but I prefer to use Textile. In this post, I note down the steps needed to make Jekyll work with Textile and how configuration is done.

RedCloth is the most common (only?) Ruby library for converting Textile into HTML. It can be used by Jekyll sites to add support for writing your posts in Textile instead of Markdown. Recently, I started to look a bit deeper into RedCloth because one of the themes that I was considering works better with a feature that is not available in RedCloth as yet.

For this reason, I decided to document down some of the things that I found as I was preparing to add this feature.

Using Textile with Jekyll

The support for Textile is added by the Jekyll Textile Converter plugin and the instructions are same as documented in their README.

• Add gem 'jekyll-textile-converter' to the Gemfile of your site and run bundle
• Add the following lines to the _config.yml to bring the plugin into the site:
  

  plugins: ['jekyll-textile-converter','RedCloth']

• Configure it (optional)

After this, any file that has an extension of .textile and has the usual Jekyll front matter, it will just work.

Using RedCloth with Windows

There are a couple of minor problems with making RedCloth work on Windows and the fixes are discussed in this PR that was merged in RedCloth recently. Hopefully, a new release will bring back support for Windows but until then, you can follow the steps that are written there.

Configuration – Jekyll

As noted in the README of the jekyll-textile-converter, you can configure Jekyll to convert files with other extensions using Textile by adding this to your _config.yml:

textile_ext: "textile,txtl,tl"

Configuration – RedCloth

RedCloth has some attributes that can be configured. The list of attributes is shown in the RedCloth source code and is also listed in the jekyll-textile-converter so that it can initialise the RedCloth converter.

If you want to set up any of these attributes for your site, add the following to your _config.yml (normally, you won’t need to add this):

redcloth:
  no_span_caps: true

Additional Information

If you decide to modify RedCloth yourself (as I want to do) and decide that you want to add a new attribute which can be configured from your Jekyll site, this is what you will need to do:

• Add the relevant code into RedCloth
• Modify jekyll-textile-converter and add the new attribute to this list so that it is recognised
• Add the property for your site to the _config.yml as explained in the previous section

This post is mainly to document what I found so that I can remember it for when I change RedCloth. Feel free to share the post (you can tag me as @onghu on Twitter or on Mastodon as @onghu@ruby.social ) or leave a comment below.