Markdown Basics

This topic covers the most important Markdown syntax.

Headings

Headings in Markdown are any line which is prefixed with a # (hash) symbol. The number of hashes indicates the level of the heading. The first content in the file after the metadata block must be the title as H1 heading (# Header). All major topics should be tagged further as header level 2 (## Header).

There are a total of 6 levels which you can make use of - but for most writing, you’ll rarely ever need more than 3.

Note

Each Markdown file must have one and only one H1 heading.
There must be a space between the last # and heading text.
Header levels 4, 5 and 6 are not visible in affixes (right side of the page) and do not have anchor points.

Example:

# This is an H1 header
## This is an H2 header
### This is an H3 header
#### This is an H4 header
##### This is an H5 header

Result:

Paragraphs and line breaks (soft return)

In the editor, enter two blank spaces before the line break, and then select Enter to begin a new paragraph.

Example:

Add two spaces before the end of the line, and then select **Enter**.(space, space, Enter)
A space gets added in between paragraphs.

Result:

Add two spaces before the end of the line, and then select Enter.

A space gets added in between paragraphs.

In-Text highlights (bold, italics)

Asterisks (*) are used to format text as bold or as italic.

To apply italics: surround the text with an asterisk *. To apply bold: surround the text with double asterisks **.

Example:

Use *italics* for values and **bold** for fields. For more information, see [Formatting](./cosmo-styles.md#formatting).  
*Italic text*  
**Bold text**  
***Bold, italicized text***

Result:

Use italics for values and bold for fields. For more information, see Formatting.
Italic text
Bold text
Bold, italicized text

Tables

Organize structured data with tables. The simplest way to create a table in Markdown is to use pipes (|) and lines. The first two lines of a table set the column headers and the alignment of elements in the table. For a header, enter a dashed line after the first line. You can align (left, centre, right) the columns by using colons (:). To start a new line, use the HTML break tag (<br/>).

Example:

| Heading 1 | Heading 2 | Heading 3 |  
| :- | :-: | -: |
| Left Aligned | Center Aligned | Right Aligned |
| ... | ... | ... <br/>second line of text |

Result:

Heading 1 Heading 2 Heading 3
Left Aligned Center Aligned Right Aligned
... ... ...
second line of text

You can also use Tables Generator.

Lists

Organize related items with lists. You can add ordered lists with numbers, or unordered lists with just bullets.

Ordered lists start with a number followed by a period for each list item. Unordered lists start with a -. Begin each list item on a new line. In a Markdown file, enter two spaces before the line break to begin a new paragraph, or enter two line breaks consecutively to begin a new paragraph.

Ordered or numbered lists

Example:

1. List item 1
2. List item 2
   1. List item 2.1
   2. List item 2.2
3. List item 3

Result:

  1. List item 1
  2. List item 2
    1. List item 2.1
    2. List item 2.2
  3. List item 3

Bullet lists

Example:

- List item 1
- List item 2
   - List item 2.1
   - List item 2.2
- List item 3

Result:

  • List item 1
  • List item 2
    • List item 2.1
    • List item 2.2
  • List item 3

Source code

Highlight suggested code segments using code highlight blocks. To indicate a span of code, wrap it with three backtick quotes (```) on a new line at both the start and end of the block.

Auto detection:

Example:

```
<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Write"/>
</AppPermissionRequests>
```

Result:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Write"/>
</AppPermissionRequests>

Define language:

Example:

```csharp
private void index(){
  MessageBox.Show("hello world");
}
```

Result:

private void index(){
  MessageBox.Show("hello world");
}

Without color:

Example:

```text
private void index(){
  MessageBox.Show("hello world");
}
```

Result:

private void index(){
  MessageBox.Show("hello world");
}

Blockquotes

Blockquotes are created using the > character before the text. Use many > characters to nest quoted text. Quote blocks of lines of text by using the same level of > across many lines.

Example:

> Single line quote
>> Nested quote
>> multiple line
>> quote

Result:

Single line quote

Nested quote multiple line quote

Alerts

The following alert types are available:

Example:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Result:

Note

Information the user should notice even if skimming.

Tip

Optional information to help a user be more successful.

Important

Essential information required for user success.

Caution

Negative potential consequences of an action.

Warning

Dangerous certain consequences of an action.

Links point users to content in the same page, in other neighboring pages, or on external sites and URLs.

Example:

- **External**: [COSMO CONSULT Website](http://www.cosmoconsult.com)
- **Internal**: [Another article](../sub/site-01.md)
- **Page Headers**: [Media header on this article](#media)
- **Link + Header**: [Header on foreign article](../sub/site-01.md#opus-quattuor-est-dolentem)

Result:

Use relative position of the target:

  • ./ = current directory
  • ../ = one directory above
  • ../media/file.demo = one directory above, in media folder, find file.demo
Tip

Best practice: All internal links should start with ./ or ../.

Caution

Avoid using:

Media

If you want to use images, add them to the repository by using the path definition used for Links.

Tip

Best practice: Upload all images in the media folder. This folder is already part of the Demo project.

Images

The following file types are supported for images:

  • .gif
  • .jpg
  • .png
Note

.bmp graphics don't work in Markdown.

Use the following syntax to add an image:

Example:

![COSMO CONSULT](../media/CosmoConsult.png "Text used by screen readers")

Result:

COSMO CONSULT

Videos

Avoid copying videos directly to the repository. Best practice here is to upload the video somewhere else and link to the video.

Example:

> [!Video https://web.microsoftstream.com/embed/video/86bf382e-556e-4100-91f4-e4dda2d53a2a?autoplay=false&amp;showinfo=true]

Result:

Horizontal rules

To add a horizontal rule, add a line that's a series of dashes ---. The line above the line containing the --- must be blank, to be not interpreted as header.

Example:

above

----
below

Result:

above

below

Useful hints

HTML

Although Markdown supports inline HTML, HTML isn't recommended for publishing to Docs, and except for a limited list of values will cause build errors or warnings.

Comment (out) syntax

Useful for sections that are not ready.

<!-- Comments -->

Example:

In the TOC:
<!-- [Managing Payables](payables-manage-payables.md)-->
In a topic:
<!-- This is a paragraph that spans more lines and I can just put the comment tag
at the beginning and end of it -->
Note

It's possible to comment out text, unless it’s a table.

Angle brackets

If you use angle brackets in text in your file - for example, to denote a placeholder - you need to manually encode the angle brackets. Otherwise, Markdown thinks that they're intended to be an HTML tag.

For example, encode <script name> as \<script name>.

Note

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.

Angle brackets don't have to be escaped in text formatted as inline code or in code blocks, see Source code.

Apostrophes and quotation marks

If you copy from Word into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up with things like this when the file is published: It’s.