Learn Markdown reference

This article provides an alphabetical reference for writing Markdown for Microsoft Learn.

Markdown is a lightweight markup language with plain text formatting syntax. The Microsoft Learn platform supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Microsoft Learn also supports custom Markdown extensions that provide richer content on the Microsoft Learn site.

You can use any text editor to write Markdown, but we recommend Visual Studio Code with the Learn Authoring Pack. The Learn Authoring Pack provides editing tools and preview functionality that lets you see what your articles will look like when rendered on Microsoft Learn.

Alerts (Note, Tip, Important, Caution, Warning)

Alerts are a Markdown extension to create block quotes that render on Microsoft Learn with colors and icons that indicate the significance of the content.

Avoid notes, tips, and important boxes. Readers tend to skip over them. It's better to put that info directly into the article text.

If you need to use alerts, limit them to one or two per article. Multiple notes should never be next to each other in an article.

The following alert types are supported:

> [!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.

These alerts look like this on Microsoft Learn:

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