As a developer, I can assure you of the importance of rich text formatting in user requests—especially in issue descriptions—for good text comprehension. It is especially important if the one who is going to comprehend an issue (for example) is constantly dealing with a lot of such issues. In practice, users unfortunately neglect rich formatting often, what results in bad readability and sometimes distorted message layouts (when some characters are treated as formatting markers). Therefore, I believe that familiarity with Redmine text formatting is essential for using this application. Luckily, the syntax of the formatting language is not too complicated, as it's based on a plain-text markup language.
Redmine currently comes with native support for two markup languages—Textile and Markdown. However, we will focus mainly on the former (while mentioning the latter whenever possible). There are two reasons for this. Firstly, most Redmine installations (still) use Textile, as it was supported by Redmine long before Markdown was added. Secondly, Textile is less used in other applications, so you most likely won't be able to learn it elsewhere.
The Textile markup language attempts to add rich formatting to plain text while not breaking its readability. Thus, list items begin with * or #, italic text is enclosed in _ (underline), and so on. This way, if someone writes text not using any formatting markers, such text will be rendered just fine (in most cases). Moreover, Textile is able to add rich formatting to plain text that does not include any special Textile rules. For example:
- Pieces of text that are separated by empty lines are rendered as paragraphs
- Paragraphs that start with
>are rendered as quotes - Strings that start with, say,
http://, are rendered as links
In other words, Textile is very simple and easy to learn. At least, most of its syntax is. However, this book is not aimed at simple things that you can learn on your own, so in this chapter you will also find some complicated advanced topics.
We will cover the following topics in this chapter:
- Formatting text in Redmine
- The Wiki syntax
Initially in Redmine, rich text formatting was implemented mainly for the integrated Wiki system that is provided by the Wiki module, which was described in the previous chapter. That's why it is still often called Wiki formatting (and that's the name I will use to refer to it from now on). Right now, however, the Wiki syntax is used not only for the Wiki pages but also for issue descriptions, comments, news, project descriptions, and so on.
The underlying markup language used for Wiki formatting can be selected on the General tab of the Settings page, which can be found in the Administration menu. Check out the following screenshot:
Thus, if the Text formatting setting is set to none, the content that you put into a Wiki-syntax-enabled text area will be shown as is, that is, any formatting will be ignored. This will also apply to the Wiki system, what means that Wiki pages will lose their formatting. However, the Wiki syntax for Redmine's internal linking (such as links to issues and Wiki pages), which will be covered further, will still be functioning! Otherwise, the Wiki system would become completely useless, particularly without support for cross-page links.
As before, for fresh Redmine installations with a fresh audience, I would recommend that you choose Markdown for the Text formatting option (see Chapter 2, Installing Redmine). Certainly, this chapter would become less useful for you in that case. Less useful but not totally useless, as the Wiki syntax has a part that is common to both Textile and Markdown.
Almost every text area for a field that supports Wiki formatting comes with the Wiki toolbar:
This toolbar does not convert the text area into a What You See Is What You Get (WYSIWYG) editor, however. It just provides an easy way to paste the most commonly used formatting markers. Unfortunately, a well-working WYSIWYG solution for Redmine currently does not exist as far as I know.
The last button in the toolbar, 
, opens a quick reference for the Wiki syntax. The page that gets opened also includes a link to more detailed documentation.
None of the buttons in the toolbar open a dialog. All of them just paste the syntax markers at the current position in the text area. Also, if the user selects part of the text in the text area, clicking on these buttons formats the selected text accordingly. Thus, if the user clicks on the 
button, the selected text will be enclosed in * (the bold marker). If the user selects several lines of the text and clicks on the 
or 
button, * or # (list markers) will be prepended at the beginning of each selected line accordingly.
The Wiki toolbar is really helpful when you have just started using Redmine and therefore do not remember all the markers. After you become a more experienced user, I believe you will prefer to type them directly in the text area (at least I do). Also, the Wiki toolbar does not cover all the available markers, so you won't be able to completely avoid typing them anyway. For this reason and because we have not covered the available syntax yet, we won't review these buttons here. However, you may play with them on your own.
In most cases, forms with Wiki-syntax-enabled text areas include the Preview link, an example of which is shown here:
This link can, and should, be used before submitting the content to Redmine to check whether it's going to be formatted correctly. When you click on this link, the preview of the content of a Wiki syntax-enabled text area will be rendered beneath the form.
Tip
Always use the Preview link, if available, before submitting content to the server. Do this even if you are sure that the markup is correct and even if you did not use any markers at all, as the content can still include some special characters or sequences of characters that may be treated as formatting markers by the core Redmine formatter or third-party extensions.
Of course, in most cases, you will be able to fix the content later after submitting it. However, if users are subscribed to the content, they will most likely get the initial version and not the fixed one. Also, further changes are sometimes logged in the change history of the resource (for example, the issue history), thus clogging it.
Wiki content can use linked images. Here, the word linked means it's hosted on the same Redmine installation, and possibly stored in the same resource (for example, an issue) and embedded in the Wiki content of the resource using the Wiki syntax. While the Wiki syntax allows the linking of images that are hosted on external websites, this can be inadmissible in many cases, for example, for security reasons or due to the load speed. So, let's discuss where you can store your linked images.
If the resource (such as an issue or a Wiki page) for which you are writing the content lets you attach files, attach your images to it. Thus, for issue notes, attach images to the issue.
However, not all resources can have attachments (that's why I have written this subsection, actually). For such resources, some users store linked images under the Files tab of the project menu, but I don't recommend doing this. Under the Files tab, your users expect to see files for downloading, for example, installation packages, documentation, samples, and so on. So, they may conclude that these images are somehow related to the project (for example, they may think of them as diagrams) and should be downloaded as well.
Therefore, I believe that in such cases the best option is to attach linked images to a specially created and dedicated Wiki page, for example, Linked-images. There, you will also be able to describe the purpose of the page and annotate images that are attached—if you want, of course. Also note that if this page won't be referenced from any other Wiki page, it will be seen only on Wiki index pages, such as Index by title and Index by date, which is perhaps good.
But what URL should you use if you store the image in a separate resource? For the same resource, it's easy (use just the filename; see the Images subsection of The Wiki syntax section), but what about a separate resource? Not so easy, but not too difficult either. To get the URL, right-click on the name of the attached file and copy the link address, as follows:
You should get a URL that ends with /attachments/<id>/<filename>. This is the URL you should use when embedding the image in a Wiki content! Also, always use the relative URL. I mean the one that starts with /, for example, /attachments/<id> or /redmine/attachments/<id> (this depends on whether your Redmine uses a subdomain—redmine is the subdomain here). And yes, <filename> is actually optional, so it can be omitted.