Markdown Reference Guide

This article is about how to use Markdown for formatting content, including headings, links, images, lists, line breaks, code blocks, block quotes, and tips for escaping characters or pasting from other sources. It serves as a comprehensive guide for creating well-structured and readable documentation using Markdown syntax.

Basic formatting

Headings

All heading levels (e.g., H1, H2, etc.), are marked by the hashtag (#) at the beginning of a line.

# H1
## H2
### H3
##### H4

Heading best practices

Also, put blank lines before and after a heading.

Links

Links can be created using several methods.

Images

Images are like links, but with an exclamation point (!) at the front of the path.

Inline style

![alt text](path to image)

When the ticket comment is submitted, the image appears in the conversation log.

To embed an image that's not hosted, first attach the image to the ticket. Then open the attachment, right-click the image, select Copy image URL, and use this link to embed your image. Doesn't work if private attachments are enabled.

Images with links

Supported in agent signatures.

[![alt text](imageurl)](linkurl)

Lists

Lists are made by using indentation and a beginning-of-line marker to indicate a list item.

Unordered lists

Unordered lists can use an asterisk (*), plus (+), or minus (-) to indicate each list item.

* One item
* Second item
* Third item
* Fourth item
* Fifth item

* One item
+ Second item
- Third item
* Fourth item
+ Fifth item

Ordered lists

Ordered lists use a number at the beginning of the line. The numbers do not need to be incremented - this will happen for you automatically by the HTML. That makes it easier to re-order your ordered lists (in markdown) as needed.

3. Step
2. Step
4. Step
1. Step

OR

1. Step
1. Step
1. Step
1. Step

Output

1. Step

2. Step

3. Step

4. Step

Nested unordered lists

* One item
* Another item
  * A sub-item
    * A deeper item
  * Back in sub-item land
* And back at the main level

Output

• One item

• Another item

  • A sub-item

    • A deeper item

  • Back in sub-item land

• And back at the main level

Note

Remember to pick a delimiter and stick it.

Nested ordered lists

1. Step one
1. Step two
   1. Sub-step a
   1. Sub-step b
1. Step three
1. Step four
   1. Sub-step a
   1. Sub-step b
1. Step five

Output

1. Step one

2. Step two

   1. Sub-step a

   2. Sub-step b

3. Step three

4. Step four

   1. Sub-step a

   2. Sub-step b

5. Step five

Nested ordered and unordered lists

You can use both types of lists to nest items. In the example below, the unordered list under the second ordered list item refers to items that aren’t sequential (no need to perform a task in a specified order).

* One item
* Another item
  1. A nested ordered list
  1. This is the second item
     * And now an unordered list as its child
     * Another item in this list
  1. One more in the ordered list
* And back at the main level

Output

• One item

• Another item

  1. A nested ordered list

  2. This is the second ordered list item

     • And now an unordered list as its child

     • Another item in this unordered list

  3. One more in the ordered list

• And back to the main level

Line breaks

You can press Shift+Enter to add the line breaks manually or use the <br> HTML tag at the end of the line.

Shift+Enter (no trailing white space)

First line with two spaces after.
And the next line.

HTML tag

First line with the HTML tag after.<br>
And the next line.

Code and syntax highlighting

Inline code

Use one `backtick` around the code. This is the markdown version of the <code> tag in HTML.

Code blocks

Use three backticks (```). This is the markdown version of the <pre> tag in HTML.

To exit a code block placed at the end of a comment, press the Enter key three times.

```powershell
Set-AdfsProperties -EnableIdPInitiatedSignonPage:\\$true
```

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

Block quotes

To create a blockquote, add a > in front of a paragraph.

Single line or paragraph

> This is some part of a blockquote.

Output

This is some part of a blockquote.

Multiple paragraphs

Block quotes can contain multiple paragraphs.

> This is the first line of a multi-line blockquote.
>

> This is the second line with a space between the paragraphs.

Output

This is the first line of a multi-line blockquote.

This is the second line of a multi-line blockquote with a space between the paragraphs.

Block quotes with other elements

Block quotes can contain other markdown formatted elements.

NOTE

Not all elements can be used. Experiment to see which ones work.

> **The quarterly results look great!**
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
>  Everything is going according to **plan**.

Output

The quarterly results look great!

• Review was off the chart.

• Profits were higher than ever.

Everything is going according to plan.

Tips and tricks

Paste Markdown from another source

If you copy text with Markdown commands from a plain text editor, the content is automatically formatted as soon as you paste it. If you don't want the content to be automatically formatted, use Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows) to paste.

The content is not automatically formatted if you copy text with Markdown commands from any type of editor, into a code block in the ticket composer. It remains "as is."

Escape characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\) in front of the character.

\* Without the backslash, this would be a bullet in an unordered list.

Output

• Without the backslash, this would be a bullet in an unordered list.

It’s also worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:

1986. What a great season.

In other words, a number-period-space sequence at the beginning of a line. To avoid this, add a backslash to escape the period:

1986\. What a great season.

Characters you can escape

You can use a backslash to escape the following characters.