When to Use Markdown

Markdown is a good choice when you want authors to focus on structure rather than exact visual styling. It works especially well for teams that prefer plain text, copy content from other text-based systems, or want a lightweight format for reusable examples and snippets.

Quick Reference

• Basic Formatting: italics, bold, combined emphasis, and strikethrough
• Headings: section titles using # characters
• Lists: bulleted and numbered lists, including nested items
• Links and Images: external links and embedded images
• Quotations and Alerts: block quotes and callout-style content
• Tables and Code Examples: structured data and inline or fenced code

Articles can be written in Markdown syntax. Markdown is a good choice when you do not want editors controlling exact presentation details, but you still want them to indicate whether content is a heading, a list, a quote, or another structural element.

This approach has a few benefits. If you later change the visual style of your documentation, you can usually update the CSS theme instead of editing every article. It also reduces the amount of presentation detail each editor needs to remember. For example, an editor only needs to know that a heading starts with ##, not exactly how that heading should look.

Basic Formatting

Markdown allows you to mark specific pieces of text with the normal formatting you would expect in a normal text editor. For instance, marking text as italicized, bold or strikethrough.

Italics

To make text italicized you should wrap it inside a single asterisk on either side of the text.

Example

Sometimes you need to *draw attention* to some text.

Renders As

Sometimes you need to draw attention to some text.

Bold

To make text have extra emphasis you should wrap it inside double asterisks on either side of the text.

Example

Sometimes you need to **draw attention** to some text.

Renders As

Sometimes you need to draw attention to some text.

If you need to make text both italics and bold, you would wrap it inside triple asterisks on either side of the text.

Example

Sometimes you need to ***draw attention*** to some text.

Renders As

Sometimes you need to draw attention to some text.

Strikethrough

If you need to strikethrough some text you would wrap it inside double tildes on both sides of the text.

Example

Sometimes you need to ~~remove attention~~ from some text.

Renders As

Sometimes you need to remove attention from some text.

Headings

Headings are denoted by a hash `#` character at the start of the line. The number of hashes denotes the heading level. For instance, 3 hashes would be equivalent to a third level heading.

Example

# Heading 1

##  Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Lists

You have two options for building lists of items. You can use both bulleted lists as well as numbered lists.

Bulleted Lists

A bulleted list is best used for unordered items, meaning the order does not matter. To build an unordered list you prefix each line with a * character followed by a whitespace character.

Example

* First item
* Second item
* Third item

Renders As

• First item
• Second item
• Third item

You can also have multiple levels of bulleted lists by prefixing the entire line with 4 whitespace characters before the asterisk character. Each set of four whitespace corresponds to one level of indentation.

Example

* First item
    * Second level
        * Third level
* Second item
* Third item

Renders As

• First item
  • Second level
    • Third level
• Second item
• Third item

Numbered Lists

Numbered lists, also called ordered lists, are best used for a sequence of items. That is, items that must be in this order for them to make sense. For example, a sequence of steps that must be performed is a good candidate for an ordered list. You create an ordered list by prefixing each line with a number, followed by a period, and then a whitespace, such as "1. ".

You can either enter your own sequential numbers or you can just always prefix each line with "1. " and it will automatically move to the next number on each line when it renders. Doing it this way can be helpful especially if the number of steps is changing quite often and you don't want to renumber the whole list each time.

Example

1. First item
2. Second item
3. Third item

Renders As

1. First item
2. Second item
3. Third item

Just like with unordered lists, you can also indent your items by four whitespace characters. If want to change how each level is displayed you can use CSS. For instance, you might want the second level to be alphabetical starting with a and the third level to be roman numerals starting with i.

Example

1. First item
    1. Second level
        1. Third level
2. Second item
3. Third item

Renders As

1. First item
   1. Second level
      1. Third level
2. Second item
3. Third item

Links

You will find it very easy to include a link to another page either on your site or on an external site. This comes in two parts. First you need to supply the title text that will become the clickable link. This is done by wrapping the title inside an opening bracket [ and a closing bracket ]. Next the actual URL gets wrapped inside an opening parenthesis ( and a closing parenthesis ).

Example

Please try our [Search](https://www.google.com/) page.

Renders As

Please try our Search page.

Images

Images use nearly the same syntax as links. The difference is that the entire expression starts with an exclamation mark (!). The link URL becomes the image source, and the text becomes the alternate text shown if the image cannot be displayed.

Example

![Sample Image](https://dummyimage.com/800x240/fff/000&text=Sample+Image)

Renders As

Quotations

Quoted text blocks can be used for a couple different things, depending on how you want to use them. But at their most basic, they are just a different way to display text. You mark text as a quote block by starting the line with a greater than > character. You can also use multiple > characters to increase the level of quotation.

As the name implies though, the most common use is to indicate a piece of quoted text. In the case of documentation, you might use this for simple callouts to make the text stand out just a bit without overstating it's content.

Example

> True humility is not thinking less of yourself; it is thinking of yourself less.
>
> C.S. Lewis

Renders As

Tables

You can even design tables in your documentation. A table is defined by the first line containing the heading titles of the columns, each column has a vertical bar | characters before and after.

The second line is the "table indicator" which tells the Markdown engine that this is a table. It is defined as one or more hyphen - characters, also surrounded by vertical bar | characters. Each column and optionally have a colon : character to specify the alignment to be used for that column.

The remaining lines specify the rows and column values of the table. Each line is a row and the column values should follow the same pattern as the header line.

Example

| Heading 1 | Heading 2 | Heading 3 | Heading 4 |
| :---- | ----: | :----: | ---- |
| Left Aligned | Right Aligned | Centered | Neutral |
| 100 | 100 | 100 | 100 |
| 200 | 200 | 200 | 200 |
| 300 | 300 | 300 | 300 |

Renders As

Code Examples

While you may not plan on writing actual programming code examples, the code examples is another way to highlight text. This comes in two flavors.

1. Inline code samples
2. Fenced code blocks

The first involves using a single back-tick ` character to open and close your inline sample.

Example

When asked to enter the contact type be sure to enter `Contact Card`.

Renders As

When asked to enter the contact type be sure to enter Contact Card.

As you can see this highlights whatever is inside the back-ticks and also switches to using a monospace font. This syntax is common to use when you are describing something that the user should type in as-is.

The second form allows you to have multiple lines of code (or plain text). You do this by using what is called a "code fence", which is three back-ticks ``` on a line to start and then another three back-ticks ``` to close the fenced block. Optionally, after the opening three back-ticks you can also include a language alias specifier which will be used for automatic syntax highlighting.

Example

```html
<p>
  This is a sample of <b>bold</b> text.
</p>
```

Renders As

<p>
  This is a sample of <b>bold</b> text.
</p>

This method is common to use when showing a full example of what a user might type in. It is also useful if you just need to make sure that the text is displayed exactly as you intended, without any automatic word wrapping or anything like that being applied.

Below you will find a list of most of the supported languages for automatic syntax highlighting, there are actually more but you aren't likely to ever use them.

Alerts

Sometimes you want to draw special attention to something. It might be something informational that they might miss if they were skimming over the text and you want to draw extra attention to it. Other times you might want to point out a common error people make so they don't make the same mistake. These are called alerts and are built very similarly to a quotation.

A quotation is prefixed by one of the following words, enclosed inside a special tag: TIP, NOTE, WARNING, IMPORTANT, CAUTION. the special tag is an opening bracket [ character, the exclamation point !, the alert word and finally a closing bracket ] character. For instance: [!TIP].

Example

> [!TIP]
> This is a tip to help the user.

> [!NOTE]
> This is a note the user should be aware of.

> [!IMPORTANT]
> This is something important that the user should pay special attention to.

> [!WARNING]
> This is a warning to the user to do or not do something.

> [!CAUTION]
> This is a caution to the user that something could be dangerous.

Renders as