Writing in Markdown

The formatting you can use in descriptions, comments and the other text fields, with examples of each.

Ticket descriptions and environments, comments, rich text custom fields and the portal's request forms are written in Markdown: plain text with a few punctuation marks that say how it should look. What you type is stored as you typed it and shown formatted. The fields that take Markdown carry a question mark that opens this page, which lists everything the renderer understands. Each example shows the text to type, then how it appears.

If you have written on GitHub, everything you know works here, including the GitHub additions: tables, task lists, alerts and struck out, inserted, highlighted, superscript and subscript text.

Paragraphs and line breaks

Leave a blank line between paragraphs. A line ending inside a paragraph is joined to the line before it, so you can wrap long lines as you like. To force a line break, end the line with a backslash or two spaces.

The first paragraph.

The second paragraph, with a\
forced line break.

The first paragraph.

The second paragraph, with a
forced line break.

Headings

Start a line with a hash and a space for a heading. More hashes make smaller headings, up to six.

# A heading

Some text under it.

### A smaller heading

Headings inside a description are shown smaller than the ticket's own title, so they organise a long description without competing with it.

Emphasis

*italic* or _italic_, **bold**, ~~struck out~~, ++inserted++ and ==highlighted== text.
Water is H~2~O and the area is x^2^.

italic or italic, bold, ~~struck out~~, inserted and highlighted text. Water is H₂O and the area is x².

Struck out and inserted text read well together in a comment that proposes a change to some wording. A single tilde or caret on its own is shown as it is; only a pair around some text has this effect.

Lists

- A bulleted item
- Another, with a list inside it:
  - indented by two spaces
  - or more

1. A numbered item
2. Another; the numbers need not be in order

- [ ] A task still to do
- [x] A task done

A bulleted item
Another, with a list inside it:
- indented by two spaces
- or more

A numbered item
Another; the numbers need not be in order

A task still to do
A task done

A task list is for reading only: the boxes show the state of the text, and ticking one means editing the text. For work that has to be tracked, use sub-tasks.

Links and images

Read [the user guide](https://albaticket.com/docs) first.
A bare address such as https://albaticket.com becomes a link by itself.

![What the error looks like](https://example.com/error.png)

Read the user guide first. A bare address such as https://albaticket.com becomes a link by itself.

An image is a link with an exclamation mark in front, and the text in the square brackets describes it for anyone who cannot see it. To show a file you have attached to the ticket, attach it first, then copy its address from the attachment list and use that as the image's address.

Another ticket is referred to by its key, such as WEB-12. When a ticket with that key exists, the key becomes a link to it wherever it is written, except inside code or another link; a key that matches no ticket is shown as written. To record the relationship on both tickets rather than only mention it, link the tickets.

A knowledge base page is referred to as [[KEY/Page title]], with the space's key before the slash, or [[KEY/Page title|other words]] to show other words. For a reader who may read the page it becomes a link showing its title; for anyone else it stays as written. See Pages and tickets.

Quotes and alerts

Start a line with a greater-than sign to quote it, as when replying to part of an email.

> The customer wrote: it fails every second time.

Then it is probably the cache.

The customer wrote: it fails every second time.

Then it is probably the cache.

A quote whose first line is one of five words in square brackets becomes an alert, a box that stands out from the text around it.

> [!NOTE]
> Something worth knowing before reading on.

> [!TIP]
> A shortcut or a better way.

> [!IMPORTANT]
> Something the reader must not miss.

> [!WARNING]
> Something that could go wrong.

> [!CAUTION]
> Something that will cause harm if ignored.

Note

Something worth knowing before reading on.

Tip

A shortcut or a better way.

Important

Something the reader must not miss.

Warning

Something that could go wrong.

Caution

Something that will cause harm if ignored.

Code

Put a command, a key or a value in backticks to show it as code in a sentence. For several lines, put three backticks on the line before and after; a language name after the opening backticks says what the block holds.

Run `mix test` and look for `ArgumentError`.

```elixir
def hello, do: :world
```

Run mix test and look for ArgumentError.

def hello, do: :world

Nothing inside code is formatted or turned into a mention or a link, so a code block is the right place for a log excerpt or a stack trace.

Tables

Separate columns with vertical bars and put a row of dashes under the header. A colon at the right end of a dashed cell aligns that column to the right; one at each end centres it. The bars need not line up.

| Browser | Version | Works |
| ------- | ------: | :---: |
| Firefox | 130     | yes   |
| Safari  | 17      | no    |

Browser	Version	Works
Firefox	130	yes
Safari	17	no

Mentions

Write an at sign and a person's username, or their name with no spaces, to mention them. When it matches somebody in the workspace, it is shown as a mention with their name and they are notified of the comment or description. An at sign that matches nobody is shown as written, and one in an email address is left alone.

@maria could you check the logs for this?

Colour, panels and cited text

Four things Jira wiki can say have no Markdown equivalent, so a little HTML is allowed for them: coloured text, cited text, a panel with its own title, and a table without a header row. They are what a ticket converted from Jira wiki uses, and you can write them yourself.

<span class="wiki-red">red</span>, <span class="wiki-orange">orange</span>,
<span class="wiki-yellow">yellow</span>, <span class="wiki-green">green</span>,
<span class="wiki-blue">blue</span>, <span class="wiki-purple">purple</span>
and <span class="wiki-grey">grey</span> text.

As <cite>The Art of Computer Programming</cite> puts it.

<div class="panel">
<div class="panel-title">Steps to reproduce</div>
<div class="panel-body">Open the board, then press the back button.</div>
</div>

<table><tr><td>a table</td><td>with no header row</td></tr></table>

The seven colours are chosen to read well on the light and the dark theme, and a colour Jira used is matched to the nearest one rather than carried over exactly. The panel's title is optional.

What is removed

A description or comment is written by whoever can edit the ticket, so nothing in it may change how the page itself looks or behaves. Everything not listed on this page is removed when the text is shown, and the words inside it are kept:

Any style attribute, and any class other than the colours and panel parts above.
Scripts, forms, frames and embedded content.
Links to addresses that would run something rather than open a page.

The text you typed is not changed. If some formatting does not appear, it is one of these, not a mistake in what you wrote.

Text imported from Jira

Tickets imported from Jira keep their original wiki markup and are shown as they were written. The first time somebody opens an editor on one of them, the wiki text is converted to Markdown and the editor shows the conversion, so you can read it over and correct it before saving. Saving stores the Markdown, and the wiki original stays in the ticket's history as the previous value. Nearly all of Jira's markup has a Markdown equivalent; the four that do not are the ones the HTML above is for.