Markdown Guide

Markdown reference

This post will not serve as a “how to” for markdown but offers a reference for writing markdown. Most of the content was taken directly from Microsoft Learn. I have copied most of the information from there to this post to have something to modify and reference for future use. I’ve simplified the content in order to focus on what is most valuable when just starting with markdown.

One of the great things about markdown is that because it is just a plain text file, you can copy it to a server without office, adobe, or some other tool installed and still view its content as long as you have some way to view a text file. You can use any text editor to write markdown. Still, it is recommended that you use something like Visual Studio Code.

Blockquotes

Blockquotes are created using the > character:

> This is a blockquote. It is usually rendered indented and with a different background color.

The preceding example renders as follows:

This is a blockquote. It is usually shown as indented and with a different background color.

Bold and italic text

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***.

For guidance on when to use bold and italic text, see text formatting guidelines.

Code snippets

Markdown supports the placement of code snippets both inline in a sentence and as a separate “fenced” block between sentences. For more information, see How to add code to docs.

Headings

This is the section to have committed to memory. Only using headings is enough to give your document organization. There are situations where you’ll have to use other markdown elements, but use them only when needed. Remember to keep your markdown readable without conversion as much as possible. Adopt minimalism everywhere possible.

# 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 the heading text.
• Each Markdown file must have one and only one H1 heading.
• The H1 heading must be the first content in the file after the YML metadata block.
• H2 headings automatically appear in the published file’s right-hand navigation menu. Lower-level headings don’t appear, so use H2s strategically to help readers navigate your content.
• HTML headings, such as <h1>, aren’t recommended, and in some cases, will cause errors.
• You can link to individual headings in a file via bookmark links.

HTML

Although markdown supports inline HTML, HTML isn’t recommended, and you will get unexpected results from some conversions. HTML can also make your document harder to read.

Images

The following file types are supported by default for images:

• .jpg
• .png

Standard conceptual images (default Markdown)

The basic Markdown syntax to embed an image is:

![<alt text>](<folderPath>)

Example:
![alt text for image](../images/Introduction.png)

Where <alt text> is a brief description of the image and <folder path> is a relative path to the image. Alternate text is required for screen readers for the visually impaired. It’s also helpful if there’s a site bug where the image can’t render.

Underscores in alt text aren’t rendered as expected unless you escape them by prefixing them with a backslash (\_). However, don’t copy file names for use as alt text. For example, instead of this:

![ADextension_2FA_Configure_Step4](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Write this:

![Active Directory extension for two-factor authentication, step 4: Configure](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Indentation

In markdown, spaces before the first character of a line determine the line’s alignment relative to the preceding lines. Indentation influences numbered and bulleted lists to render multiple levels of nesting in a hierarchical or outline format.

To indent text to align with a preceding paragraph or an item in a numbered or bulleted list, use spaces.

The following two examples show how indented paragraphs render based on their relationship to other paragraphs.

1. This is a numbered list example (one space after the period before the letter T).
 This sentence is indented three spaces.
 This code block is indented three spaces.
 
- This is a bulleted list example (one space after the bullet before the letter T).
 This sentence is indented two spaces.
 > [!TIP]
 > This tip is indented two spaces.
 - This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T).
 This sentence is indented four spaces.
 > This quote block is indented four spaces.

The example above renders as:

1. This is a numbered list example (one space after the period before the letter T).

This sentence is indented three spaces.

This code block is indented three spaces.

• This is a bulleted list example (one space after the bullet before the letter T).

This sentence is indented with two spaces.

[!TIP] This tip is indented two spaces.

• This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T).

This sentence is indented four spaces.

This quote block is indented four spaces.

Links

For information on the syntax for links, see Use links in documentation.

Lists (Numbered, Bulleted, Checklist)

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 increment your lists manually.

Don’t use letters in lists, including nested lists. They don’t render correctly when published to Microsoft Learn. 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:

1. This is
2. a parent-numbered list
3. and this is
4. a nested numbered list
5. (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 within a document.

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 a dashed line:

|This is |a simple |table header|
|----------|-----------|------------|
|table |data |here |
|it doesn't|actually |have to line up nicely!|

This renders as follows:

You can align the columns by using colons:

| Fun | With | Tables |
| :------------------- | -------------------: |:---------------:|
| left-aligned column | right-aligned column | centered column |
| $100 | $100 | $100 |
| $10 | $10 | $10 |
| $1 | $1 | $1 |

Renders as follows:

Inconsistent column widths between tables

You may notice that the column widths of the tables in your articles look odd or inconsistent. This behavior occurs because the length of text within the cells determines the layout of the table. Unfortunately, there’s no way to control how the tables render. This is a limitation of markdown. Even though it would look nicer to have the width of table columns be consistent, this would have some disadvantages too:

• Interlacing HTML code with markdown makes topics more complicated and discourages community contributions.
• A table that you make look good for a specific screen size may end up looking unreadable at different screen sizes as it preempts responsive rendering.

Now that you have made it this far. I suggest heading to the markdown guide to continue learning.