Markdown Syntax

In YouTrack, you can format text using the Markdown markup syntax. You can format text in issue descriptions, supplemental text fields, comments, and work items descriptions. This type of markup is offered as an alternative to the visual formatting tools in the rich text editor. To learn more about the available options for formatting text, see Rich Text Editor.

The Markdown implementation in YouTrack follows the CommonMark specification with extensions. These extensions support formatting options that are not included in the formal specification like checklists, strikethrough text, tables, user mentions, and issue links.

To see a complete list of formatting options, click the Markdown link to open the syntax list, then click the help icon. This opens the YouTrack Markup Reference page in your browser.

The YouTrack Markup Reference page provides a sandbox. Use the sandbox to preview the formatted output. When the text is formatted to your liking, copy the contents of the sandbox and paste it into the issue description or comment.

Availability

In addition to issue fields, YouTrack supports Markdown in project descriptions, Markdown Notes widgets, user agreements, system-wide banners, and custom messages on the login page. Many of the extensions that are described here are not available in these fields. For example, the extensions that support embedded content from Google apps, embedded video, YouTube video, issue links, article links, and user mentions are only supported in issues and articles. The ability to parse HTML tags is exclusive to issues and articles as well.

To ensure that the content you enter in these fields is formatted correctly, use the preview pane to the left of the input field.

Character Formatting

You can apply character formatting to a range of inline text with the following Markdown syntax.

Style	Syntax
Strong	Surround text with two asterisks (`**`) or two underscore characters (`__`).
Emphasis	Surround text with single asterisks (`*`) or single underscore characters (`_`).
Strikethrough	Surround text with two tildes (`~~`).
Code	Surround text with one or more backquotes (`) to format an inline code span.
Combinations	Surround text with single underscore characters or two tildes inside two asterisks. Surround text with three asterisks to apply strong emphasis.

You should read this, it's **very important**.
You _might_ want to read this.
~~Never mind~~ - it wasn't _that_ important.

Let's try a few `combinations`:
**This text is strong, ~~this text is strong with strikethrough~~,
    and _this text is formatted with strong emphasis_**
***This text is formatted with strong emphasis too.***

Headings

Headings help you organize your text into different sections. They are differentiated from the rest of the text through larger boldface font sizes.

To apply a heading style, start the line with one to six number signs(#). Follow the number signs with a space character and enter the heading text. The number of # signs determines the heading level.

YouTrack also supports an alternative syntax for heading levels 1 and 2:

For heading level 1, enter one or more = characters on the following line.
For heading level 2, enter one or more - characters on the following line.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1 - Alternative Syntax
========

Heading 2 - Alternative Syntax
--------

Paragraphs and Line Breaks

Contiguous lines of text belong to the same paragraph. Use the following guidelines to structure your content into paragraphs and enter line breaks.

To start a new paragraph, leave a blank line between lines of text.
To start a new line inside a paragraph, enter two or more trailing spaces at the end of the line of text. For a more visible alternative, enter a single backslash (\).

Even though this text is written on two separate lines,
it is parsed as a single paragraph.

This paragraph is separated from the previous paragraph
by a blank line.

This text is parsed as a single paragraph.
The two trailing spaces at the end of the previous line start a new line.\
The backslash character also starts a new line.

Thematic Breaks

Create sections in your content with thematic breaks. Use any of the following methods to add a thematic break:

Three or more underscores (___)
Three or more minus signs (---)
Three or more asterisks (***)

Note that thematic breaks can interrupt paragraphs and can include whitespace characters. You cannot have more than three spaces of indent, and you must use the same non-whitespace character.

The underscores on the next line create a thematic break below this paragraph.
___
The minus signs below must be separated from this paragraph by a blank line.
If not, they are parsed as a level 2 heading.

----
Three or more asterisks also create a thematic break.
****

Block Quotes

Use block quotes to call special attention to a quote from another source. You can apply character formatting to inline text inside the quoted block.

To set text as a quote block, start the line with one or more > characters. Follow these characters with a space and enter the quoted text. The number of > signs determines the level of nesting inside the quote block.

If your quote spans multiple paragraphs, each blank line must start with the > character. This ensures that the entire quote block is grouped together.

> Use block quotes to emulate reply text.
> This line is part of the same quote.

This line is not formatted and does not belong to the quote block.

> This block spans multiple paragraphs.
>
> The second paragraph is grouped with the previous paragraph in the same quote block.
> Character formatting is _also_ supported inside the **quote block**.

> Quote blocks can also be nested.
>> When you start a new line with additional > characters,
>>> it simulates a threaded conversation.

Indented Code Blocks

You can format blocks of text in a monospaced font to make it easier to identify and read as code.

To format a code block in Markdown, indent every line of the block by at least four spaces. An indented code block cannot interrupt a paragraph, so you must insert at least one empty line between a paragraph and the indented code block that follows. The input is processed as follows:

One level of indentation (four spaces) is removed from each line of the code block.
The contents of the code block are literal text and are not parsed as Markdown.
Any non-blank line with fewer than four leading spaces ends the code block and starts a new paragraph.

Start an indented code block following a paragraph with a blank line and at least four spaces of indentation:

    This is a code block.

    Blank lines between indented lines do not end the code block.

    Here is some HTML:
            
        &lt;div class="footer"&gt;
            &copy; 2009—2017 JetBrains · All rights reserved
        &lt;/div&gt;
        
This line of text is not indented. It ends the code block and starts a new paragraph.

Fenced Code Blocks

Unlike indented code blocks, fenced code blocks have an info string that lets you specify which language is used for syntax highlighting. Language-specific highlights make the code easier to read.

Syntax highlighting is supported for a range of languages. YouTrack detects and highlights code in C, C++, C#, Java, JavaScript, Perl, Python, Ruby, and SH automatically. To highlight code in other languages, set the language in the info string (the line with the opening code fence). The following languages are supported: apollo (AGC/AEA Assembly Language), basic, clj (Clojure), css, dart, erlang, hs (Haskell), kt (Kotlin), latex (LaTeX), lisp, llvm, lua, matlab, ml, mumps, n (Nemerle), pascal, proto, scala, sql, tcl, tex, vb, vhdl, wiki, xq, and yaml.

When you set the language in the info string, the language tag is shown in the line above the code.

YouTrack recognizes a set of language aliases that are interpreted by the Markdown implementation in GitHub. This includes the following language aliases:

Language Alias	Language Name	Syntax Highlighter Applied by YouTrack
fsharp	F#	fs
kts	Kotlin Script	kt
octave	Matlab	matlab
latex	Latex	tex
vb.net or vbnet	Visual Basic .NET	vb
yml	YAML	yaml

To set a block of text as a block of code with syntax highlighting, follow these guidelines:

To create a fenced code block that spans multiple lines of code, set the text inside three or more backquotes (```) or tildes (~~~).
Open and close the block with the same character.
Use the same number of characters to open and close the code fence.
Specify the language or language alias that you want to use for syntax highlighting immediately after and on the same line as the set of characters that you use to open the fenced code block.

Set multiple lines of code in fenced code blocks.

```
action: (ctx) => {
    workflow.check(!ctx.issue.isChanged('votes'), workflow.i18n('Voting for a resolved issue is not allowed.'));
},
```

The following code block uses syntax highlighting for Haskell:
```hs
-- Point-free style
fib :: Integer -> Integer
fib = (fibs !!)
where fibs = 0 : scanl (+) 1 fibs

-- Explicit
fib :: Integer -> Integer
fib n = fibs !! n
where fibs = 0 : scanl (+) 1 fibs
```

Stack Traces

Fenced code blocks can be formatted as stack traces. To format code as a stack trace:

Open and close a fenced code block with exactly three backquotes (```) or tildes (~~~). Close the code block with the same character you used to open the code block.
Enter stacktrace in the opening line of the code fence to set the language.
Paste the stack trace into the fenced code block.

When the stacktrace is formatted, references to source code and other issues are set as links. If the feature is enabled in your development environment, you can click these links to open the target reference in your IDE. For more information, see Open Stack Traces in an IDE.

The following code block is formatted as a stacktrace.
This fenced code block uses tildes, and sets the language as "stacktrace".

~~~stacktrace
java.lang.NullPointerException
at my.stack.trace(Of.java:123)
~~~

HTML Blocks

An HTML block is a group of lines that is treated as raw HTML markup. The block begins wherever YouTrack detects a valid HTML tag and ends with the line where the matching end tag is present. The content between the start and end tags is rendered in HTML without escaping.

There are situations where valid HTML content is not displayed as written.

All markup is matched against a predefined list of allowed tags. Content inside tags and attributes that might be exploited by attackers is filtered out.
You can't have more than three space characters in front of the tag that starts the HTML block. Blocks that start with four or more spaces are formatted as indented code.

With HTML markup, you can use the following features to enhance issue content:

Feature	Description
Collapsible blocks	Use the `<details>` tag to hide supplemental information. A clickable control lets readers expand to show and collapse to hide the block of text.
Custom text color	Use the `<font>` tag to set text in a specified color. For example: `<font color="red">red text</font>`.
Line breaks	Use `<br>` tags everywhere you want to start a new line - even inside table cells.
Easy-mode block quotes	Use the `<blockquote>` tag to format blocks of text that include empty lines as a single block of quoted text. This means you can paste an entire block of text between these tags and the content is formatted as a block quote. To achieve the same result with the native syntax for block quotes in Markdown, you have to add the `>` character to each empty line.

Inline text is also parsed for HTML markup. Text that is set between an opening angle bracket (<) and a closing angle bracket (>>) is matched against the predefined list of allowed tags. If YouTrack considers it to be safe, the tag is parsed as HTML. The content inside the tags is rendered in HTML without escaping.

If you're pasting content into an issue that's rendered as HTML and want to show the text as written, you need to escape the markup. To learn how, see Escaping HTML.

For collapsible blocks, the text inside the summary is always visible. Users can click the summary to show or hide the details.

<details>
    <summary>
        <font color="red">SPOILER ALERT</font>
    </summary>
            Soylent Green is made from human flesh
</details>

HTML is great for formatting tables. It's a bit more flexible than Markdown syntax.

<table>
    <tr>
        <th>Contributor</th>
        <th>Contribution Type</th>
    </tr>
    <tr>
        <td>Cecilia</td>
        <td>Code<br>Reviewing Pull Requests<br>Answering Questions</td>
    </tr>
    <tr>
        <td>Jakob</td>
        <td>Maintenance<br>Hosting Infrastructure<br>Build Tools</td>
    </tr>
    <tr>
        <td>Sylvia</td>
        <td>Design<br>Documentation</td>
    </tr>
    <tr>
        <td>Rob</td>
        <td>Translation</td>
    </tr>
</table>

Block quotes are a lot easier to format with HTML as well. One set of tags is all you need!

<blockquote>Your time is limited, so don't waste it living someone else's life.

Don't be trapped by dogma – which is living with the results of other people's thinking.
</blockquote>
— Steve Jobs

Lists

Use the following syntax to create lists:

To create an unordered list, start the line with a minus sign (-), asterisk (*), or plus sign (+).
To create an ordered list, start the line with a number followed by a period (1.) or a close parenthesis (1)). The start number of an ordered list is determined by the number of its initial list item. The numbers of subsequent list items are disregarded.
To nest an unordered list inside an unordered or ordered list, indent the line with two spaces. Nesting ordered lists is not supported.

The following list **must** begin with the number 1:
1. Only lists that start with 1 are allowed to interrupt paragraphs.
1. Subsequent numbering is irrelevant.
0. You can start a new line with any number as long as you use the same delimiter character.
2) This item uses a different delimiter and starts a new ordered list, starting with the number 2.

This list can start with any number:

4) The empty line means that the list does not interrupt a paragraph.
1) The ordered list continues to increment the numbering from the previous list item.
123456789) Use any number fewer than ten characters. This number is parsed as the third item in the ordered list.

* Start unordered lists with -, *, or +.
+ You don't even have to use the same character for each list item.
- Pro tip: * and + require the Shift key. - doesn't. Format faster with the minus sign.
  * Nest unordered list items with two spaces.
    * Unordered lists support multiple levels of nesting.

Checklists

Checklists are not supported in the CommonMark specification. This functionality has been implemented with an extension. While similar to the Task list items (extension) in GitHub Flavored Markdown, the implementation in YouTrack is slightly different.

Use the following syntax to create checklists:

Start a checklist just as you would an unordered list. Enter a minus sign (-), asterisk (*), or plus sign (+) at the beginning of the line. This is interpreted as a list item marker.
Follow the list item marker with one or more spaces, a left bracket ([), either a whitespace character or the lowercase letter x, and then a right bracket (]). This is interpreted as a checklist item marker.
- If the character between the brackets is a whitespace character, the checkbox is unchecked.
- If the character between the brackets is a lowercase letter x, the checkbox is checked.
Enter an arbitrary string of text following the checklist item marker. The text is displayed inline with the checkbox.

TODO:
* [x] This item is marked as complete. The checkbox is checked.
- [ ] This item is incomplete. The checkbox is unchecked.
+ [ ] As with unordered lists, you can start the line with an asterisk, minus sign, or plus sign.
    - [ ] Nest checklist items with two spaces.
        -  [ ] Checklists support multiple levels of nesting.

Tables

Tables are a great tool for adding structure to your content. Use the following syntax to create tables:

To create columns, use vertical bars (|). The outer bars are optional.
Separate the header row from the rest of the table with three or more minus signs (---).
To align column text to the right, add a colon (:) to the right side of the minus signs in the separator row.
To center text inside the column, add colons (:) to both sides of the minus signs.
To align column text to the left, add a colon (:) to the left side of the minus signs in the separator row.

Note that the columns don't have to line up perfectly in the raw Markdown. You can also add character formatting to text inside the table.

Kitchen Cleanup Rotation

| Month    | Assignee | Backup |
| -------- | -------- | ------ |
| January  | Dave     | Steve  |
| February | Gregg    | Karen  |
| March    | Diane    | Jorge  |

Here's the same text with additional formatting and alternative syntax.
+ The text in the first column is right-justified.
+ The text in the second column is centered.
+ The text in the third column is left-justified.
+ The Markdown is stripped down to the minimum syntax that is required to render the table.

Month | Assignee | Backup
---:|:---:|:---
**January** | Dave | _Steve_
**February** | Gregg | _Karen_
**March** | Diane | _Jorge_

Links

There are several ways to insert links with Markdown.

Style	Format
Inline	Wrap link text with brackets `[ ]` followed by the URL in parentheses `( )`.
Inline with tooltip	Use inline formatting and add the tooltip in quotation marks after the URL.
Reference	Replace the URL with an arbitrary, case-insensitive reference, wrapped in brackets `[ ]`. Add the reference text and URL to another place in the input field. To define the reference, enter the same tag name wrapped in brackets, followed by a colon, followed by the URL. These references are not displayed in the rendered markdown. Use reference-style links when you have multiple links to the same target.

YouTrack has also extended the standard syntax to include autolinks.

[inline link](https://www.jetbrains.com.cn/en-us)
[inline link with tooltip](https://www.jetbrains.com.cn/en-us "JetBrains: Development Tools for Professionals and Teams")
[reference link][1]

[1]: https://www.jetbrains.com.cn/en-us

Autolinks

Autolinks are absolute URIs and email addresses that are set inside angle brackets (< >). They are parsed as links, with the URL or email address as the link label. Unlike links that let you specify link text and tooltips, this syntax simply converts the URL or email address into a clickable link.

YouTrack supports an extended syntax for URLs. Any string that is parsed as a URL is converted into a clickable link, even without the angle brackets. Email addresses that are not set inside angle brackets are displayed as text.

Both of these URLs are parsed as links:

<https://youtrack.jetbrains.com/issues>
https://youtrack.jetbrains.com/issues

Email addresses are also converted into "mailto" links when set in angle brackets:

<webmaster@jetbrains.com>

Issue Links

A sequence of characters that matches an existing issue ID is automatically parsed and transformed into a link to the corresponding issue.

On the YouTrack server for JetBrains (youtrack.jetbrains.com),
the following string is parsed as an issue ID
and set as a link to the corresponding issue: JT-43793

Links to Knowledge Base Articles

A sequence of characters that matches an existing article ID is automatically parsed and transformed into a link to the corresponding article in the knowledge base. When users move the pointer over the link, a custom tooltip displays additional information about the article, including its title, author, and creation date.

Link to an article in the knowledge base with tooltip.

In the screenshot above, the reference in the string is parsed as an article ID
and set as a link to the corresponding article: JT-A-79

User Mentions

User mentions are also set as links. When you enter the @, YouTrack suggests users whose usernames match the input that follows. When you complete the selected user or enter a valid username, the @mention is replaced with the user's full name and set as a link.

Images

The syntax for images is similar to the syntax for links. To insert an inline image:

Start the line with an exclamation point (!).
Wrap the alt text with brackets ([ ]).
Set the image URL and tooltip in parentheses (( )).

You can also use the reference style for images. To insert an image reference:

Start the line with an exclamation point (!).
Wrap the alt text with brackets ([ ]).
Set the image reference in brackets ([ ]).
Define the image reference in another location with the syntax [tag]: image URL "tooltip".

Here's an image link to the JetBrains logo on Wikipedia:

![JetBrains logo](https://upload.wikimedia.org/wikipedia/commons/1/1a/JetBrains_Logo_2016.svg "JetBrains")

This link to the JetBrains logo uses the reference style:
![JetBrains logo][logo]

[logo]: https://upload.wikimedia.org/wikipedia/commons/1/1a/JetBrains_Logo_2016.svg "JetBrains"

Markdown also supports images as links.
Just wrap the entire image reference in brackets then add the target URL in parenthesis after the image reference.
People use this syntax to insert a thumbnail image that links to a video on a video sharing platform.

Here's a reference to the latest video promotion for YouTrack:

[![YouTrack — Maintain Order In A World of Chaos](https://img.youtube.com/vi/rhAunB7UQFQ/sddefault.jpg)](https://www.youtube.com/watch?v=rhAunB7UQFQ)

Image Attributes

You can set custom height and width dimensions for images. These attributes are also available for YouTube videos, embedded video, and embedded content from Google apps.

Use the following guidelines to set custom display dimensions:

Wrap the size attributes in curly braces ({ }) and put it after the content reference.
Specify either height or width attribute, to scale the image proportionally while preserving the original aspect ratio. Use both attributes to set desired dimensions explicitly.
Specify the value of an attribute as an integer to set the absolute size in pixels. For example, width=250 is parsed as 250px.
Specify the width attribute as a percentage to determine its size relative to the visible display area. For example, width=25% resizes an image to occupy 25% of the visible display area, preserving the original aspect ratio.
This feature is only supported for the width attribute. References to the height attribute as a percentage are ignored.

Here's an inline reference to the Markdown logo on Wikipedia that has been rescaled to fit the visible display area:

![Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png "Markdown"){width=100%}

Image Attachments

You can insert an inline reference to an image that is already attached to the issue. The image is displayed in the description, comment, or work item where the reference is placed.

Use the same syntax that is used for images, replacing the image URL with the filename of the attachment.

Start the line with an exclamation point (!).
Wrap the alt text with brackets ([ ]).
Set the filename and optional tooltip in parentheses (( )).

The following markup inserts an image with the filename `image.png`.
The words "image attachment" are used for both the alt text and the tooltip.

![image attachment](image.png "image attachment")

File Attachments

In addition to images, you can add links to any file that’s attached to an issue. Links that reference image files or PDFs open the file directly in the browser. For all other file types, the link lets the user download a copy of the file to their local machine.

The syntax for adding links to files is similar to the format for adding links to URLs:

Style	Format
Inline	Wrap link text with brackets `[ ]` followed by the filename with extension in parentheses `( )`.
Inline with tooltip	Use inline formatting and add the tooltip in quotation marks after the filename.
Reference	Replace the URL with an arbitrary, case-insensitive reference, wrapped in brackets `[ ]`. Add the reference text and filename to another place in the input field. To define the reference, enter the same tag name wrapped in brackets, followed by a colon, followed by the filename with extension. These references are not displayed in the rendered markdown. Use reference-style links when you have multiple links to the same target file.

Here’s an example that uses each of these three styles to add links to a file named `markdown-rocks.html`.

[inline](markdown-rocks.html)
[inline with tooltip](markdown-rocks.html "Markdown implementation in YouTrack is A-M-A-Z-I-N-G !!!")
[reference][1]

[1]: markdown-rocks.html

Embedded Videos

Using the syntax for image attachments, you can embed a video file that is attached to the issue. The video player is shown inline with the surrounding text. You can play the video directly in the embedded player.

Start the line with an exclamation point (!).
Wrap the alt text with brackets ([ ]).
Set the filename in parentheses (( )).

This functionality is only available for files in MPEG-4, Ogg, and WebM format.

The following markup embeds a video with the filename `MP4-video.mp4`.

![embedded video](MP4-video.mp4)

Mermaid Diagrams

Mermaid diagrams are a type of diagramming language and tool used to generate flowcharts, sequence diagrams, Gantt charts, and other visual representations of data or processes. You can create a Mermaid diagrams using a simple markdown-like syntax, which makes them easy to write and understand.

If you already have the code for your Mermaid diagram, you can paste it directly into the rich text editor.

To copy an existing Mermaid diagram to the rich text editor in Markdown mode:

Click the Markdown button in the formatting toolbar to switch to visual editing mode.
Click the Code block icon in the formatting toolbar or enter ``` to open a fenced code block.
Specify the programming language to use for the code block as mermaid. The language attribute is specified on the same line immediately after the backticks that open the fenced code block.
Paste the code for your Mermaid diagram into the code block area in the rich text editor, then enter ``` to close the fenced code block, if needed.

To build a Mermaid diagram directly in the rich text editor, start a fenced code block and specify mermaid as the programming language. Write the code for your diagram inside the fenced block. The diagram is rendered in the preview pane as you type.

LaTeX Mathematical Notation

When you have a mathematical formula formatted in LaTeX, and you need to show it in an issue or an article, you can put it into a fenced code block and specify the latex language there. YouTrack recognizes the LaTeX markup and renders the formula.

YouTrack's implementation supports most environments for different types of mathematical notation and structures, including align, equation, gather, array, and matrix. It also supports older notation that uses the double dollar sign ($$) to denote display math mode. In display math mode, equations, formulas, or mathematical expressions are displayed on separate lines in the center of the page.

When you edit an issue in YouTrack Classic, you can see the rendered formula in the preview. When you save your changes, the issue displays the rendered output.

When you edit an article or an issue in YouTrack Lite, you can see a preview of the rendered formula in Visual mode.

YouTrack uses the KaTeX library for processing LaTeX formulas. For the full list of supported symbols and functions, see the library reference.

Backslash Escapes

When you have characters that are parsed as Markdown that you want to show as written, you can escape the character with the backslash (\).

Backslashes before non-markup characters are shown as backslash characters.
Escaped characters are treated as regular characters. Their usual meaning in Markdown syntax is ignored.
Backslash escapes do not work in fenced code blocks, inline code spans, or autolinks.

Here are a few examples of backslash escapes:

\*not emphasis*
\`not an inline code span`
1\. not an ordered list
\* not an unordered list
\# not a heading

\This is not a backslash escape - the escaped character is not a markup character.

Escaping HTML

If you’re pasting code into an issue and you don’t want it rendered as HTML, use one of the following techniques to escape the markup:

Make some space — any line of text that is indented with four or more spaces is automatically formatted as an indented code block in Markdown.
Fence it in — set the code inside three or more backquotes (```) or tildes (~~~), forming a " code fence ." Fenced code blocks even let you specify the language (like html) to enable syntax highlighting.
Slash it back — any time you have characters that you want to show as written, escape the character with a backslash (\).

Last modified: 09 October 2024