Textile or Markdown?

Good readability helps improve perception. Rich formatting is very important for issue tracking software as it allows us to highlight more important things, in this way drawing special attention to them. In Redmine, rich formatting can be achieved using a lightweight markup language—Textile or Markdown—and is supported almost in every text area. Both of these markup languages use plain-text formatting syntax.

Textile has been used by Redmine as the default and the only available formatter for many years. It is greatly supported and perfectly tested. Any experienced Redmine user is familiar with Textile and many Redmine plugins extend its syntax. Particularly for these reasons, the majority of Redmine installations, including the official website Redmine.org, use this formatter. So, most Redmine users definitely use Textile.

However, I did not see Textile being used by any other application except Redmine. On the contrary, Markdown seems to have become the de facto standard for rich formatting that is based on plain text. Thus, it is used by GitHub (in fact, it was GitHub that made it so popular) and Stack Overflow. It can be said that most developers who use a markup language use Markdown.

This means that for a fresh installation, if your target audience have not gotten used to Textile yet, you should probably select Markdown. Also, currently Redmine does not come with any converter from Textile to Markdown and I'm not sure whether it ever will (as it's complicated). So, if you choose Textile for your fresh installation, you will probably be tied to it forever. On the other hand, 3.1 is actually the first Redmine version for which the Markdown formatter is not considered to be experimental any more (it was added in 2.5). This means that this formatter has just entered the intensive testing phase (you can still help with this though). Another possible reason for keeping Textile as your formatter is that many existing Redmine users, if any of them are going to use your installation, will probably expect Textile to be used. So, generally you are better off asking your users.

But let's not be too verbose and compare the basic rules of these formatters:

	Textile	Markdown
Bold text	*Bold*	**Bold**
Italic text	_Italic_	*Italic*
Underline text	+Underline+	Not available
Inline code	@inline code@	`inline code`
Pre-formatted text	<pre> ... <pre>	~~~ ... ~~~
Syntax highlighting	<pre><code class="ruby"> ... </code></pre>	~~~ ruby ... ~~~
Bullet list	* Item 1 * Item 2	* Item 1 * Item 2
Numbered list	# Item 1 # Item 2	1. Item 1 2. Item 2
Headings	h1. Heading 1 h2. Heading 2 ... h6. Heading 6	# Heading 1 ## Heading 2 ... ###### Heading 6
Links	"Anchor":http://link	[Anchor](http://link)
Images	!image_url(Title)!	
Tables	|_.Table|_.Heading| |Cell |Cell |	|Table|Heading| |-----|-------| |Cell |Cell |

Still, which one is more powerful? Markdown is known to be more feature rich in general as, for example, it supports some HTML tags. However, its Redmine implementation is limited. Thus, no HTML tags are actually supported under Redmine. This can nonetheless change in the future, of course. On the contrary, the long usage history of Textile by Redmine has made it more powerful at the moment. See also Chapter 6, Text Formatting.