So far, we have discussed the way in which text formatting is integrated into Redmine. Now we'll focus exclusively on the syntax rules.
The supported syntax rules can be divided into special rules (for example, lists and tables) and the rest. So, the rest actually includes not only the basics but also rules that are very simple and therefore do not need a separate subsection. Moreover, these are the rules that you are going to learn right now. But let's start with the basic principles.
A Textile or Markdown document is a plain-text document. The new line character in such a document is treated as a <br /> tag in HTML; that is, the rest of the text after the new line character in the current paragraph is moved to a new line.
A paragraph is separated from the previous and next paragraphs by an empty line, that is, two new line characters. Thus, the following text will be formatted as a single paragraph:
Redmine is a flexible project management web application. Written using the Ruby on Rails framework, it is cross-platform and cross-database.
Alternatively, you can start each paragraph with p. (there should be a space after the dot):
p. Redmine is a flexible project management web application. p. Written using the Ruby on Rails framework, it is cross-platform and cross-database.
But again, paragraphs must be separated by an empty line. Otherwise, the p. in the third line will just be ignored and shown as is inside the paragraph.
The p. marker stands for paragraph and is converted into the HTML <p> tag. But in fact, the effect of using p. is usually the same as not using it, because Textile uses the HTML <p> tag for every paragraph that does not have any marker at the beginning of the line anyway.
Similar to p., the h1., h2., h3., h4., h5., and h6. markers are converted into HTML's <h1>, <h2>, <h3>, <h4>, <h5>, and <h6> tags accordingly. These markers can be used to add headings to a Wiki content. To see how all the heading levels are formatted, let's use the following code:
h1. First heading h2. Second heading h3. Third heading h4. Fourth heading h5. Fifth heading h6. Sixth heading
This code is rendered as shown in the following screenshot:
As you can see, these headings define sections of the Wiki document, each of which can be edited independently using the pen icon 
on the right. Headings down to the fourth level will also be shown in the table of contents (I will explain how to enable it later in this chapter).
These are the basic blocks that define styles for paragraphs. Now it's time for basic inline styles.
Let's start with checking how the following text will be formatted:
This is the difference between *strong* and **bold**. Inline cite looks ??this way??. Inline text can be +inserted+ or -deleted-. This is the difference between _emphasize_ and __italics__. Also Redmine supports ^superscript^ and ~subscript~.
Here is the corresponding screenshot:
You should have noticed an odd thing about strong and bold, as well as emphasized and italic styles. In most cases, * and **, as well as _ and _ _, are the same (and look the same), except that they are converted to different HTML tags. Here is the full list of HTML analogs of these Textile markers (and their Markdown analogs):
|
Textile |
HTML |
Markdown |
|---|---|---|
|
*...* |
|
**...** |
|
**...** |
| |
|
??...?? |
| |
|
+...+ |
| |
|
-...- |
|
~~...~~ |
|
_..._ |
|
*...* |
|
_ _.._ _ |
| |
|
^...^ |
|
^... |
|
~...~ |
|
Sometimes, you may want to use short names or phrases for something that can need a more detailed explanation. In such cases, you can use footnotes and acronyms to let readers quickly check out the details.
A footnote consists of two parts. The first part is a number, which should be specified inline using square brackets, for example, Some text[1] (there should be no space between the text and the marker). The second part should be specified separately—preferably at the bottom of the document—using fnX., where X is the footnote number. Like p. and hX., this marker should be at the start of the line. Also, as this is a so-called block marker, each footnote should be separated from other lines by empty lines.
Acronyms are specified inline using parentheses. Their syntax is ABC(Text), where ABC is an all-caps word that is going to be shown on the page, and Text is the description that will be shown when the user hovers the mouse arrow over the visible part. Also, as with footnotes, there should be no space between the acronym and its description.
So now, let's check out how the following Textile code will be formatted:
In Redmine[1] Wiki pages can be exported to PDF(Portable Document Format), HTML(HyperText Markup Language) and TXT(Plain text). fn1. Flexible project management web application written using Ruby on Rails.
This is what we get:
To visually separate parts of the text, you can use --- (dashes), ***, or _ _ _ (underscores) between paragraphs (separated from the paragraphs by empty lines). These markers will produce a horizontal line (made with the HTML <hr> tag). All of these markers work in Markdown as well.
Sometimes, the formatting needs to be disabled. If this is the case, to disable the processing of some part of the text by Textile, use the special <notextile> tag. Here is an example:
<notextile>This text will be shown *as is*.</notextile>
But note that this won't disable link generation—it will turn off only the formatting. New line characters and empty lines won't be processed either, so the no-textile (the text inside <notextile>) text will always be shown in a single paragraph.
For applications such as Redmine, it's important to be able to embed quotes, especially in issue comments and forum messages. Luckily, the Redmine Wiki formatting implementation allows us to do this. Moreover, the appropriate forms usually provide UI elements for quoting original messages.
In Redmine, quotes can be embedded in two ways:
- By default, to format a text as a quote, Redmine uses the
>marker at the beginning of the line (yes, it's another block marker). As this marker supports nesting, you can use it as follows:>> Initial message > Reply to initial message
Here is a screenshot that shows how this text will be rendered:
Note
This syntax works for both Textile and Markdown, but in Textile, the
>marker does not have to be separated by an empty line from the previous paragraph. Moreover, the empty line will break the left gray line, which indicates that the paragraph is a quote. On the contrary, in Markdown, the empty line is required. - Textile supports one more way of specifying quotes—with the
bq.marker. Generally, both ways produce visually identical results (because both rely on the HTML<blockquote>tag), butbq.does not support nesting. However, thebq.marker, like the<blockquote>tag, supports theciteparameter:bq.:http://www.redmine.org Redmine is a flexible project management web application. Written using the Ruby on Rails framework, it is cross-platform and cross-database.
Here, the syntax is as follows:
bq.:cite Text
Note that
citecan be an absolute or relative URL or a named anchor (that starts with#). This parameter is not displayed or used by browsers, but it can be used by search engines to locate the original message.
Redmine Wiki formatting supports bulleted and numbered lists. Bullet list items can be created with the * marker, and numbered list items can be created with the # marker. Both should be placed at the start of the line and followed by a space (unlike the strong * marker, which should be followed by a word).
Bulleted and numbered lists can be nested. To add a nesting level, just add another marker at the beginning. Let's see how the following example will be rendered using Textile:
# The first item ## Nested item ### Next nesting level # The second item
The following screenshot shows the result:
You can also mix types of nested lists. For example, check out the following code:
# The first item #* Nested item #** Next nesting level # The second item
Images can be embedded in Wiki content using the ! rule, the syntax of which is as follows:
!Options.ImageURL(Title)!:HREF
Here, Options. (with the dot), (Title), and :HREF are optional.
The image URL can be absolute or relative. Thus, to embed an image that was attached to a different resource (described in the Where to store linked images? subsection of the Formatting text in Redmine section), you need to use the relative URL:
!/attachments/110!
Of course, in this case, users who have access to the current Wiki content will also be required to have access to the resource to which the image is attached.
Images that are attached to the current resource can be embedded just by using their file names, like in this example:
!9144_06_15.png!
The optional HREF parameter can be used to turn the image into a clickable link that points to a URL:
!redmine-logo.png!:http://www.redmine.org
The optional Options parameter can be used to align the image relative to the text. Supported alignment options are <, =, and >. These options align the image to the left, center, and right correspondingly. For example, let's check out how the following markup is rendered:
!<.redmine-logo.png! Redmine is a flexible project management web application. Written using the Ruby on Rails framework, it is cross-platform and cross-database.
This is what we get:
Finally, the Title parameter can be used to specify the alternative text for the image. This text is going to be displayed when the browser fails to load it (it's an analog of the alt attribute of the HTML <img> tag).
Redmine's Wiki formatting supports two types of links: normal and internal.
If the text contains strings that start with http://, https://, ftp://, ftps://, sftp://, or www., they will be rendered as links automatically. The same will be done with email addresses—they will be converted into mailto: links.
Also, normal links can be created using the following syntax:
"Anchor(Text)":Link
Here, Anchor is the text that is going to become clickable, Text is the optional link title that will be displayed when the user hovers the mouse arrow over Anchor, and Link is the URL that the link will point to.
Redmine Wiki formatting would be incomplete without support for internal links. In particular, its Wiki system would be useless without cross-page links.
The syntax for internal links was developed especially for Redmine, so it's common to both formatters: Textile and Markdown.
It's essential for any Wiki system to support cross-page links, as such links are the only way to navigate the Wiki (other than the awkward Wiki index).
In Redmine's Wiki, cross-page links can be created using this syntax:
[[Project:Page#NamedAnchor|Title]]
Everything except Page is optional here. Page is the name of the Wiki page, that is, the last component of the page URL. For example, in the URL http://www.redmine.org/projects/redmine/wiki/RedmineWikis, the page name is RedmineWikis.
Sometimes, you may need to create a link to a section of a Wiki page. Sections that are created using the h1. to h4. markers always include named anchors, which can be referenced in links. Moreover, the named anchor is always automatically generated from the title of the heading. Therefore, we can use just the heading title as NamedAnchor. Here is an example:
[[Wiki#First heading]]
Tip
In the URL, NamedAnchor is used as a component that is also known as the fragment identifier. As not all characters are URL-safe, Redmine sanitizes heading titles and values that you specify in Wiki links. However, if in some cases you need to specify the already sanitized named anchor, you can determine it by hovering your mouse arrow over the heading and then over the pilcrow (¶) that will appear to the right of the heading . The sanitized value will be seen in the URL, that should be shown on the status bar, after the # sign (that is, as the URL fragment).
In practice, you will rarely want to use the page name as the title of the link (which is also known as the anchor). And, to use a different piece of text, you should put it into the Wiki link as Title (after the | sign). Here is an example:
See [[Another-Wiki-page-name|this page]] for details.
Finally, if the page that you are about to link to belongs to a different project, you should prefix its name in the Wiki link with the project name or identifier, as follows:
[[Mastering Redmine:Wiki-page-name]]
If the projects that you host on your Redmine installation are somehow related, you may want to create links from some projects to others. For such cases, Redmine supports project links that have this syntax:
project:Name
Here, project is the keyword that indicates the project link, and Name is the project name or identifier. If the project name contains special characters, for example, spaces, it should be put in double quotes.
Project links point to the overview page of the project and always use the project name as the anchor (that is, visible text).
Linking to a version is a very useful feature, and I personally use it quite often. Thus, it can be used in news, when you describe the new features of a version; in issues, if you want to specify which version is affected; and so on. Version links point to the version page and always use the version name as the anchor. The syntax is like this:
version#ID version:Name
Here, version is the keyword that indicates that this is a version link, Name is the version name (which can be enclosed in quotes), and ID is the numeric ID, which can be seen in the URL of the version page (the last component).
To link to a version in a different project, prefix it with the project identifier, like in this example:
redmine:version:3.1.0
Most likely, you will use issue links even if you don't plan to. That's because their syntax is very natural and obvious. It's just #X, where X is the issue number.
If the issue is closed, its anchor, that is, the issue number, will be formatted as strikethrough. If the user hovers the mouse arrow over the issue link, the hint box will show the subject and status of the issue.
Resolving an issue is a process that often engages not only the assignee, but also users, customers, QA engineers, and more. In such cases, it is very useful to be able to reference a particular note (history entry) of the issue, especially if that note explains some details. To create a link to an issue note, use this syntax:
#X-Y #X#note-Y
Here, Y is the number of the history entry, which can be seen on the issue page.
While the ability to attach files to a resource can be used to store images that will be embedded in Wiki content of that resource, the main goal of attachments is actually different. Thus, we usually store files in a Wiki page, an issue, a forum topic, or any other resource just to let users download them. In such cases, we need to reference the attached files somewhere in the Wiki content. To do this, instead of using text such as "check the file attached to this page" we can use the following syntax:
attachment:filename.ext
This will produce the link to the attached file, which will trigger its download when users click on it. Instead of filename.ext, use the actual filename of the attachment. Enclose the filename in quotes if it contains spaces or other special characters.
However, note that the file that you link to in Wiki content must be attached to the resource that this Wiki content is part of. This means that you can't create links to project files (the ones that are under the Files tab).
Sometimes, you may want to mention news about the project in your Wiki content. In such cases, you can use the news syntax rule, as follows:
news#ID news:Title
Here, ID is the numeric ID of the news. This ID can be seen in the URL of the news page (the last component). Title is the title of the news (which can be enclosed in quotes). When rendered, news links always use the title as the anchor.
If the news that you are about to link to is in a different project, you should prepend the syntax rule with the project identifier, like this:
project-identifier:news#ID project-identifier:news:Title
The very same rule is available for documents:
document#ID document:Title
Here, ID is the numeric ID of the document, which can be seen in the URL of the document page, and Title is the document title (which can be put in quotes).
To create a link to a document in a different project, use the project identifier at the beginning, as follows:
project-identifier:document#id project-identifier:document:Title
Linking to forums is very much the same:
forum#ID forum:Name
Again, ID is the numeric ID of the forum (you know how to find it) and Name is the name (title) of the forum.
Forum links can be used, for example, to advise users on where they can discuss their questions. However, in practice, you will most likely want to link to a specific topic of the forum or even to a specific message in a topic (for example, because it contains details about the issue).
From a technical point of view, a reply in a topic is the same object as the topic itself (a topic is just the first message in a thread). So, to link to both of them, you need to use message links. The syntax for such links is as follows:
message#ID
Here, ID is the unique numeric ID of the message.
Unfortunately, the message ID which is to be used in such links is not shown in the list of topic messages, and individual replies do not have URLs to take it from. This means that it should be determined in a special way. Check out this screenshot:
As you can see in the previous screenshot, when you hover your mouse arrow over the message subject, on the status bar of the browser, you should see the reply URL. In this particular case, it is the following:
http://mastering-redmine.com/boards/1/topics/2?r=4#message-4
Let's discuss what this URL tells us. The message ID of the reply is 4 (#message-4). The first message of the topic has ID 2 (topics/2) and is actually the topic. Also, the numeric ID of the forum is 1 (boards/1).
As in the case of other links, to make a reference to a forum or message in another project, just prepend the project identifier with a colon (:) at the end.
Repository support is one of the most powerful features of Redmine, so it is not surprising that the Wiki syntax comes with support for many repository-related links.
As you might know, SCM systems are intended for managing and tracking revisions. Each revision that is created by a commit contains changes that were made to files. So, links to revisions may be needed to let users know when, by whom, and how files were changed. However, the way to create such links depends on the type of revision ID, which in turn depends on the type of SCM.
Some SCMs, such as Subversion, use numeric IDs for commits. To link to revisions in such SCMs, you should use this syntax:
Repository|rX
Here, X is the revision number and Repository is the repository identifier, which should be specified if you have more than one repository in the project. Also, the Repository| part is optional. Here are some examples:
r128 Core|r9868
Other SCMs, such as Git, use string IDs for revisions (for example, special hashes). For them, you should use the following syntax:
commit:Repository|ID
Here, ID is the revision ID, commit is the keyword, and Repository is the optional repository identifier. Let's see some examples:
commit:0e1a622a commit:Core|9fde11f9
Like with issue links, when the user hovers the mouse cursor over a revision link, the hint box with the commit message is shown.
In addition to revisions, you may need to reference a particular source file and even its line, for example, to show where you think the problem lies. In such cases, use the following syntax:
source:Repository|Path@X#LY
Here, Path is the path to the file in the repository, X is the optional revision ID (numeric or not), Y is the optional line number, and Repository should be used if this is not the default repository in the project. Here are some examples:
source:trunk/lib/redcloth3.rb source:redmine|trunk/lib/redcloth3.rb source:trunk/app/helpers/application_helper.rb@7248 source:trunk/app/helpers/application_helper.rb#L779
You can also use a repository link to let users download a file from the repository. In this case, use the following syntax:
export:Repository|Path
Also, all of these links (revision, source, and download) can be prepended with the project identifier if you want to reference a revision or a file from a different project.