Microsoft Q&A Markdown reference
Microsoft Q&A supports a rich-web editor experience, so you would never have to worry about editing the content in Markdown. In the case you do, here is a reference for writing Markdown for Q&A.
Markdown is a lightweight markup language with plain text formatting syntax. learn.microsoft.com (Learn) supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Learn and Q&A also supports custom Markdown extensions that provide richer content on the site. Q&A uses a subset of the extensions supported in Learn' documentation. This article provides an alphabetical reference.
You can see more information on the Learn Markdown reference article.
Code snippets
Block quote
> This example is a blockquote. It's usually rendered indented and with a different background color.
The preceding example renders as follows:
This is a blockquote. It's usually rendered indented and with a different background color.
Code blocks
You can add the code language to a code block for richer rendering.
```csharp
public static void Log(string message)
{
_logger.LogInformation(message);
}
```
The preceding example renders as follows:
public static void Log(string message)
{
_logger.LogInformation(message);
}
Emojis
Q&A will convert an emoji short code to its respective Unicode characters:
This is a test with a :).
The preceding example renders as follows:
This is a test with a 😃.
Formatting
To format text as bold, enclose it in two asterisks:
This text is **bold**.
To format text as italic, enclose it in a single asterisk:
This text is *italic*.
To format text as both bold and italic, enclose it in three asterisks:
This text is both ***bold and italic***.
To format text as strikeout, enclose it with two surrounding it by two tildes:
This text is ~~strikeout~~.
Headers
Q&A supports six levels of Markdown headings:
# This is a first level heading (H1)
## This is a second level heading (H2)
...
###### This is a sixth level heading (H6)
- There must be a space between the last
#and heading text. - Each question, answer, or comment must have one and only one H1 heading.
HTML
If you enter HTML content, then content will not be rendered. Instead, it will show as plain text.
Images
The Learn custom :::image::: extension supports standard images, complex images, and icons.
:::image source="<folderOrURLPath>" alt-text="<alt text>":::
Where <alt text> is a brief description of the image and <folderOrURLPath> is a relative path to the image or its URL. Alternate text is required for screen readers for the visually impaired. It's also useful if there's a site bug where the image can't render. Don't copy file names for use as alt text. For example, instead of this:
:::image source="./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG" alt-text="ADextension_2FA_Configure_Step4":::
Write this:
:::image source="./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG" alt-text="Active Directory extension for two-factor authentication, step 4: Configure":::
Links
Links are easy to add in Q&A. Links point users to content another page in Q&A or another trusted source.
[Link text](<FullURL>).
[Microsoft Q&A products page](/answers/products).`
Link text
The words that you include in the link text should be friendly. In other words, they should be normal English words or the title of the page that you're linking to.
Do not use "select here." for the "Link text". It's bad for search engine optimization and doesn't adequately describe the target.
Important
All links must be secure (https vs http) whenever the target supports it (which the vast majority should).
Example:
For more information, see the [Microsoft Q&A products page](/answers/products).
The above example renders as:
For more information, see the Microsoft Q&A products page.
Auto links
Links will be autoformatted for any string that starts by: https://, https://, ftp://, mailto:, tel:, or www. (resolves to https://www.)
Lists (Numbered, Bulleted)
Numbered list
To create a numbered list, you can use all 1s. The numbers are rendered in ascending order as a sequential list when published. For increased source readability, you can increase your lists manually.
Don't use letters in lists, including nested lists. They don't render correctly when published. Nested lists using numbers will render as lowercase letters when published. For example:
1. This is
1. a parent numbered list
1. and this is
1. a nested numbered list
1. (fin)
This renders as follows:
- This is
- a parent numbered list
- and this is
- a nested numbered list
- (fin)
Bulleted list
To create a bulleted list, use - or * followed by a space at the beginning of each line:
- This is
- a parent bulleted list
- and this is
- a nested bulleted list
- All done!
This renders as follows:
- This is
- a parent bulleted list
- and this is
- a nested bulleted list
- All done!
Whichever syntax you use, - or *, use it consistently in your content.
Tables
The simplest way to create a table in Markdown is to use pipes and lines. To create a standard table with a header, follow the first line with dashed line:
|This is |a simple |table header|
|----------|-----------|------------|
|table |data |here |
|it doesn't|actually |have to line up nicely!|
This renders as follows:
| This is | a simple | table header |
|---|---|---|
| table | data | here |
| it doesn't | actually | have to line up nicely! |