Writing in Tuleap

This section covers the general rules that apply on texts in Tuleap.

Markdown

Tuleap supports writing Text content in Markdown format. To be more precise, Tuleap supports the CommonMark specification for Markdown.

Here is a link to an explanation of Markdown Syntax that will help you understand how to write Markdown.

If you’re already a little bit familiar with it, check the Markdown syntax cheat-sheet for a quick reminder.

Code Highlighting

Tuleap also adds a few extensions to make life easier. In Markdown, you can write “code fence” blocks to show little snippets of code. For example:

```typescript
function add(a: number, b: number): number {
  return a + b;
}
```

These snippets are syntax highlighted when rendered in HTML. There are more than 250 languages supported by the underlying lib used for the syntax highlighting, PrismJS.

Graphs

You can also write graphs in a text format called Mermaid in Markdown code blocks:

Flow-chart example:

```mermaid
  graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

This will produce a flow-chart graph like this:

At the time of writing (Tuleap 12.7), Tuleap uses Mermaid v8 and supports following graph type:

The configuration is Strict and cannot be modified. It means that clicks are forbidden and texts are encoded.

Charts can be quite large, don’t worry. There is a zoom built-in, just click on the graph and it will show the diagram in a dedicated, full screen modal. You can zoom-in and out with the mouse wheel and move as in a map.

Where can I write Markdown ?

In Tuleap Trackers Text artifact fields as well as in Follow-up comments,
in Tuleap Test Management Step Definitions,
in Tuleap Git for markdown documents,
in Project dashboard Note widget.

Tuleap references

References are a powerful tool that allow cross-referencing of Tuleap objects. Based on a text pattern, Tuleap automatically creates hyperlinks to the desired object.

When typing a follow-up comment or a commit message, any text containing the pattern XXX #NNN will be interpreted as a reference to the object of type XXX with ID number NNN.

For instance, artifact #123 is recognized as a reference to artifact number 123, and Tuleap automatically creates a hyperlink that directly points to the details of artifact 123.

You may also reference an object that belongs to another project. In that case, use either XXX #project_id:NNN or XXX #project_name:NNN to reference object XXX number NNN belonging to project which ID is project_id or which short name is project_name. For instance, doc #myproj:567 is a reference to the document 567 of the project myproj.

Some reference patterns may need more than one parameter. In this case, use / as a separator between parameters. For example, git #a_repo/6eef1d01 creates a reference to the git commit 6eef1d01 in the repository a_repo

Platform and projects can define their own references.