This is the third post in my short series on the Textile text processor in Textpattern CMS. In my previous posts I’ve introduced you to what Textile is and how you can use it to format text content in your articles. In this post, I’m going to demonstrate how you can fine-tune the integration of Textile in Textpattern so it works as you want it to.
In the first instance, it’s important to know that if you don’t ever use Textile, then you can essentially leave it turned on and not suffer ill effects. Likewise, Textile can be turned off from the administration panel: go to Administration -> Preferences and look for ‘Use Textile (or your locale equivalent). There are three options here:
- Use Textile
- Convert linebreaks
- Leave text untouched
‘Use Textile’ is set by default, choosing ‘Leave text untouched’ is essentially the same as turning Textile off and ‘Convert linebreaks’ occupies the middle ground of doing some basic processing; as the name suggests, your article line breaks will be converted into paragraph and line breaks. A single line break equates to a line break in Textile, whereas two line breaks (an empty line) will indicate a paragraph break.
When you’ve decided whether Textile should be enabled in preferences, you can then choose to override this setting on a per-article basis, should you wish to. In each article editing page, there are two sidebar menus for choosing whether Textile formatting should be applied to the article body and/or the article excerpt. Again, these have three settings available (‘Use Textile’, ‘Convert linebreaks’ and ‘Leave text untouched’) and inherit their default settings from your site preferences.
At the time of me writing this, there is no native way to have Textile set for just the article body or the article excerpt by default. However, if you want to achieve this, it’s possible with a the upm_textile_toggle plugin. This provides more control than the native, global setting. I speak from personal experience of this plugin as I had a need to use Textile in my article bodies, but not in the excerpt. I was using the <txp:excerpt /> tag to populate an ordered list (<ol>) with list items (<li>) and didn’t want the paragraph breaks in my list items. I could, however, insert a space at the beginning of the excerpt which would tell Textile to leave the text untouched, but that involves me remembering to take an action every time I write an article. Using the upm_textile_toggle plugin takes that action away from me, and as such I don’t need to have that space.
As a final point, if you have comments enabled in Textpattern then you can have Textile enabled for them, too. There are security implications for having raw (X)HTML in comments, so the majority of it will be converted to plain text, but you can enable Textile for your commentators in the Administration -> Preferences -> Advanced panel. The following Textile functions will be enabled if you enable the ‘Allow more Textile markup in comments’ toggle:
- ordered and unordered lists
- extended block syntax (blockquotes and code blocks, for example)
A good way to see if Textile is right for you, and for some further reading, is to try the Textile sand box. Next time we meet I’ll be going into detail on some more Textile tags which deal with more advanced substitution, but are still pretty easy to understand. I do hope you can join me.