Docs Markdown reference

  • Article
  • xix minutes to read

This commodity provides an alphabetical reference for writing Markdown for docs.microsoft.com (Docs).

Markdown is a lightweight markup linguistic communication with plain text formatting syntax. Docs supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Docs also supports custom Markdown extensions that provide richer content on the Docs site.

You can use any text editor to write Markdown, simply we recommend Visual Studio Lawmaking with the Docs Authoring Pack. The Docs Authoring Pack provides editing tools and preview functionality that lets yous run across what your manufactures volition look like when rendered on Docs.

Alerts (Note, Tip, Of import, Circumspection, Warning)

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

Avert notes, tips, and important boxes. Readers tend to skip over them. It's improve to put that info direct into the article text.

If y'all need to use alerts, limit them to one or two per commodity. Multiple notes should never exist adjacent to each other in an article.

The following alarm types are supported:

              > [!Notation] > Data the user should detect even if skimming.  > [!TIP] > Optional information to assistance a user be more successful.  > [!Of import] > Essential information required for user success.  > [!CAUTION] > Negative potential consequences of an action.  > [!WARNING] > Dangerous certain consequences of an activity.

These alerts look like this on Docs:

Notation

Information the user should discover even if skimming.

Tip

Optional information to assist a user be more successful.

Of import

Essential data required for user success.

Caution

Negative potential consequences of an action.

Warning

Dangerous certain consequences of an action.

Angle brackets

If you use angle brackets in text in your file (for case, to announce a placeholder), you need to manually encode the angle brackets. Otherwise, Markdown thinks that they're intended to exist an HTML tag.

For case, encode <script name> as &lt;script proper noun&gt; or \<script proper noun>.

Bending brackets don't accept to be escaped in text formatted equally inline code or in code blocks.

Apostrophes and quotation marks

If you copy from Word into a Markdown editor, the text might comprise "smart" (curly) apostrophes or quotation marks. These demand to be encoded or inverse to bones apostrophes or quotation marks. Otherwise, you end upwards with things like this when the file is published: It’southward

Here are the encodings for the "smart" versions of these punctuation marks:

  • Left (opening) quotation mark: &#8220;
  • Right (endmost) quotation mark: &#8221;
  • Right (endmost) single quotation mark or apostrophe: &#8217;
  • Left (opening) unmarried quotation marker (rarely used): &#8216;

Tip

To avoid "smart" characters in your Markdown files, rely on the Docs Authoring Pack'due south smart quote replacement feature. For more than data, meet smart quote replacement.

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. Information technology is usually rendered indented and with a different background color.

Bold and italic text

To format text as bold, enclose information technology 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 every bit both assuming and italic , enclose it in 3 asterisks:

              This text is both ***bold and italic***.

For guidance on when to utilise assuming and italic text, see text formatting guidelines.

Code snippets

Docs Markdown supports the placement of code snippets both inline in a sentence and every bit a carve up "fenced" block betwixt sentences. For more information, meet How to add lawmaking to docs.

Columns

The columns Markdown extension gives Docs authors the ability to add together column-based content layouts that are more flexible and powerful than basic Markdown tables, which are but suited for true tabular information. You can add up to 4 columns, and utilise the optional bridge aspect to merge ii or more columns.

While the columns extension still works, we no longer recommend information technology for creating custom layouts. We've found that many custom cavalcade layouts have accessibility problems or otherwise violate Docs style guidelines. Don't create custom layouts. Utilize standard Docs features.

The syntax for columns is as follows:

              :::row:::    :::cavalcade span="":::       Content...    :::cavalcade-end:::    :::column span="":::       More content...    :::column-end::: :::row-end:::

Columns should simply contain bones Markdown, including images. Headings, tables, tabs, and other complex structures shouldn't be included. A row can't accept any content exterior of column.

For instance, the following Markdown creates one column that spans two cavalcade widths, and one standard (no bridge) column:

              :::row:::    :::cavalcade span="2":::       **This is a two-bridge column with lots of text.**        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc       ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec       rutrum non eros eget consectetur.    :::cavalcade-cease:::    :::column bridge="":::       **This is a unmarried-bridge column with an image in information technology.**        ![Doc.U.Ment](media/markdown-reference/document.png)    :::column-end::: :::row-cease:::

This renders as follows:

This is a ii-span column with lots of text.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec rutrum not eros eget consectetur.

This is a single-span cavalcade with an image in it.

Doc.U.Ment

Docs supports HTML comments if y'all must comment out sections of your article:

              <!--- Here's my comment --->

Warning

Do non put private or sensitive information in HTML comments. Docs carries HTML comments through to the published HTML that goes public. While HTML comments are invisible to the reader's eye, they are exposed in the HTML underneath.

Headings

Docs supports 6 levels of Markdown headings:

              # This is a kickoff level heading (H1)  ## This is a 2nd level heading (H2)  ...  ###### This is a sixth level heading (H6)
  • There must be a space betwixt the final # and heading text.
  • Each Markdown file must have ane and only one H1 heading.
  • The H1 heading must exist the starting time content in the file subsequently the YML metadata cake.
  • H2 headings automatically appear in the right-mitt navigating menu of the published file. Lower-level headings don't appear, so use H2s strategically to assist readers navigate your content.
  • HTML headings, such as <h1>, aren't recommended, and in some cases will cause build warnings.
  • Yous can link to private headings in a file via bookmark links.

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.

Images

The following file types are supported by default for images:

  • .jpg
  • .png

To support other image types, such as .gif, you must add them equally resources in docfx.json:

              "resource": [   {     "files" : [       "**/*.png",       "**/*.jpg,       "**/*.gif"     ],

Standard conceptual images (default Markdown)

The basic Markdown syntax to embed an image is:

              ![<alt text>](<folderPath>)  Example: ![alt text for paradigm](../images/Introduction.png)

Where <alt text> is a brief description of the image and <binder path> is a relative path to the image. Alternate text is required for screen readers for the visually dumb. It's also useful if at that place's a site problems where the image can't render.

Underscores in alt text aren't rendered properly unless y'all escape them by prefixing them with a backslash (\_). However, don't re-create file names for apply as alt text. For instance, instead of this:

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

Write this:

              ![Agile Directory extension for 2-gene authentication, step iv: Configure](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Standard conceptual images (Docs Markdown)

The Docs custom :::paradigm::: extension supports standard images, complex images, and icons.

For standard images, the older Markdown syntax will all the same work, but the new extension is recommended considering it supports more powerful functionality, such as specifying a localization scope that's different from the parent topic. Other advanced functionality, such every bit selecting from the shared image gallery instead of specifying a local prototype, will be available in the future. The new syntax is as follows:

              :::image blazon="content" source="<folderPath>" alt-text="<alt text>":::

If type="content" (the default), both source and alt-text are required.

Complex images with long descriptions

You can too use this extension to add together an paradigm with a long clarification that is read past screen readers but not rendered visually on the published page. Long descriptions are an accessibility requirement for complex images, such as graphs. The syntax is the following:

              :::epitome blazon="complex" source="<folderPath>" alt-text="<alt text>":::    <long description here> :::epitome-stop:::

If blazon="circuitous", source, alt-text, a long description, and the :::image-stop::: tag are all required.

When your changes are in preview or published, you tin can check whether the long description exists by right-clicking on the image and selecting Inspect (when using Microsoft Edge browser, although other browsers have similar features). This action brings you to the image source in the HTML code, underneath which you'll find a visually-hidden course. Expand the dropdown on this form, and you'll find your long clarification:

Screenshot of the HTML for an image and its long description.

Automatic borders

The :::epitome::: extension also supports the border holding, which automatically adds a 1-pixel gray edge effectually your image. The edge holding is truthful by default for content and circuitous images, and then you'll get the border automatically unless you explicitly add the property with a value of imitation. The border property is false by default for icon images.

The border property is the recommended manner to add a edge. Don't create your ain borders manually.

Specifying loc-telescopic

Sometimes the localization telescopic for an image is dissimilar from that of the commodity or module that contains it. This tin can cause a bad global experience: for example, if a screenshot of a production is accidentally localized into a language the product isn't bachelor in. To prevent this, you tin specify the optional loc-scope attribute in images of types content and circuitous, and is required for screenshots that show a product with a different localization telescopic than the article or module that contains it.

Icons

The image extension supports icons, which are decorative images and should not take alt text. The syntax for icons is:

              :::image type="icon" source="<folderPath>":::

If type="icon", source should be specified but alt-text shouldn't be.

The border belongings is false past default for icons. If your decorative image requires the standard paradigm edge, explicitly add border="truthful" to the :::image::: tag.

Included Markdown files

Where markdown files demand to be repeated in multiple articles, you tin can use an include file. The includes feature instructs Docs to supercede the reference with the contents of the include file at build time. You can apply includes in the post-obit ways:

  • Inline: Reuse a common text snippet inline with within a sentence.
  • Block: Reuse an entire Markdown file every bit a cake, nested within a section of an article.

An inline or cake include file is a Markdown (.doc) file. It can contain any valid Markdown. Include files are typically located in a common includes subdirectory, in the root of the repository. When the article is published, the included file is seamlessly integrated into it.

Includes syntax

Block include is on its own line:

              [!INCLUDE [<title>](<filepath>)]

Inline include is within a line:

              Text before [!INCLUDE [<title>](<filepath>)] and later.

Where <title> is the name of the file and <filepath> is the relative path to the file. INCLUDE must be capitalized and in that location must be a space before the <title>.

Here are requirements and considerations for include files:

  • Apply cake includes for significant amounts of content--a paragraph or two, a shared procedure, or a shared section. Don't use them for anything smaller than a sentence.
  • Includes won't be rendered in the GitHub-rendered view of your article because they rely on Docs extensions. They'll be rendered only subsequently publication.
  • Write all the text in an include file in complete sentences or phrases that don't depend on preceding or following text in the article that references the include. Ignoring this guidance creates an untranslatable string in the article.
  • Don't embed include files within other include files.
  • /Includes folders are excluded from build. Therefore, images stored in /includes folders and referenced in included files won't be displayed in published content. Store images in a /media folder exterior the /includes folder.
  • Equally with regular articles, don't share media between include files. Apply a separate file with a unique name for each include and article. Store the media file in the media folder that'south associated with the include.
  • Don't utilize an include every bit the simply content of an article. Includes are meant to exist supplemental to the content in the rest of the commodity.

Indentation

In Markdown, spaces before the first character of a line determine the line'due south alignment relative to the preceding lines. Indentation peculiarly 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 detail in a numbered or bulleted listing, use spaces.

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

              1. This is a numbered listing example (i space afterwards the period before the letter T).    This sentence is indented 3 spaces.    This code block is indented three spaces.     - This is a bulleted listing example (one infinite subsequently the bullet before the letter T).   This judgement is indented 2 spaces.   > [!TIP]   > This tip is indented two spaces.   - This is a second-level bullet (indented 2 spaces, with 1 space after the bullet before the alphabetic character T).     This judgement is indented four spaces.     > This quote cake is indented four spaces.

The example above renders every bit:

  1. This is a numbered list example (one space afterwards 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 (i 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 ane space later on the bullet before the letter T).

      This judgement is indented four spaces.

      This quote block is indented four spaces.

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

Lists (Numbered, Bulleted, Checklist)

Numbered listing

To create a numbered list, you can utilise all 1s. The numbers are rendered in ascending order equally a sequential list when published. For increased source readability, y'all can increment your lists manually.

Don't utilise letters in lists, including nested lists. They don't render correctly when published to Docs. 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 listing 1. (fin)

This renders equally follows:

  1. This is
  2. a parent numbered list
    1. and this is
    2. a nested numbered listing
  3. (fin)

Bulleted list

To create a bulleted list, utilize - or * followed past a infinite at the outset of each line:

              - This is - a parent bulleted list   - and this is   - a nested bulleted list - All done!

This renders equally follows:

  • This is
  • a parent bulleted list
    • and this is
    • a nested bulleted listing
  • All done!

Whichever syntax you use, - or *, use information technology consistently within an article.

Checklist

Checklists are bachelor for use on Docs via a custom Markdown extension:

              > [!div class="checklist"] > * List item one > * List item 2 > * List item 3

This example renders on Docs similar this:

  • List item ane
  • List item two
  • Listing detail three

Utilize checklists at the outset or finish of an article to summarize "What will you acquire" or "What take yous learned" content. Do not add random checklists throughout your manufactures.

Adjacent step activeness

Yous can utilize a custom extension to add together a next step activeness button to Docs pages.

The syntax is as follows:

              > [!div class="nextstepaction"] > [push text](link to topic)

For example:

              > [!div class="nextstepaction"] > [Learn about adding code to articles](code-in-docs.md)

This renders as follows:

You tin can use any supported link in a next step action, including a Markdown link to another web folio. In virtually cases, the adjacent activeness link will be a relative link to another file in the same docset.

Non-localized strings

Yous can use the custom no-loc Markdown extension to identify strings of content that y'all would like the localization process to ignore.

All strings called out volition be case-sensitive; that is, the string must match exactly to be ignored for localization.

To mark an individual string equally not-localizable, use this syntax:

              :::no-loc text="String":::

For case, in the following, only the single example of Document volition be ignored during the localization process:

              # Heading 1 of the Document  Markdown content within the :::no-loc text="Certificate":::.  The are multiple instances of Certificate, certificate, and documents.

Annotation

Use \ to escape special characters:

                Lorem :::no-loc text="Find a \"Quotation\""::: Ipsum.

You tin can also use metadata in the YAML header to mark all instances of a string within the current Markdown file as non-localizable:

              author: cillroy no-loc: [Global, Strings, to be, Ignored]

Note

The no-loc metadata is not supported as global metadata in docfx.json file. The localization pipeline doesn't read the docfx.json file, so the no-loc metadata must be added into each private source file.

In the post-obit instance, both in the metadata title and the Markdown header the give-and-take Document will be ignored during the localization process.

In the metadata description and the Markdown main content the word document is localized, because it does not start with a uppercase D.

              --- championship: Championship of the Document author: author-name description: Clarification for the certificate no-loc: [Championship, Document] --- # Heading 1 of the Certificate  Markdown content inside the certificate.

Selectors

Selectors are UI elements that let the user switch between multiple flavors of the same commodity. They are used in some md sets to address differences in implementation across technologies or platforms. Selectors are typically almost applicable to our mobile platform content for developers.

Because the same selector Markdown goes in each commodity file that uses the selector, nosotros recommend placing the selector for your article in an include file. Then you can reference that include file in all your article files that employ the same selector.

There are two types of selectors: a unmarried selector and a multi-selector.

Single selector

              > [!div course="op_single_selector"] > - [Universal Windows](../articles/notification-hubs-windows-shop-dotnet-get-started/) > - [Windows Phone](../articles/notification-hubs-windows-telephone-get-started/) > - [iOS](../articles/notification-hubs-ios-get-started/) > - [Android](../articles/notification-hubs-android-get-started/) > - [Kindle](../articles/notification-hubs-kindle-get-started/) > - [Baidu](../articles/notification-hubs-baidu-get-started/) > - [Xamarin.iOS](../manufactures/partner-xamarin-notification-hubs-ios-get-started/) > - [Xamarin.Android](../articles/partner-xamarin-notification-hubs-android-go-started/)

... volition be rendered like this:

  • Universal Windows
  • Windows Phone
  • iOS
  • Android
  • Kindle
  • Baidu
  • Xamarin.iOS
  • Xamarin.Android

Multi-selector

              > [!div class="op_multi_selector" title1="Platform" title2="Backend"] > - [(iOS | .NET)](./mobile-services-dotnet-backend-ios-get-started-push.physician) > - [(iOS | JavaScript)](./mobile-services-javascript-backend-ios-get-started-push.md) > - [(Windows universal C# | .NET)](./mobile-services-dotnet-backend-windows-universal-dotnet-become-started-button.md) > - [(Windows universal C# | Javascript)](./mobile-services-javascript-backend-windows-universal-dotnet-become-started-push.md) > - [(Windows Phone | .Cyberspace)](./mobile-services-dotnet-backend-windows-phone-go-started-push.doctor) > - [(Windows Telephone | Javascript)](./mobile-services-javascript-backend-windows-phone-go-started-push.doctor) > - [(Android | .Net)](./mobile-services-dotnet-backend-android-become-started-button.md) > - [(Android | Javascript)](./mobile-services-javascript-backend-android-get-started-push.md) > - [(Xamarin iOS | Javascript)](./partner-xamarin-mobile-services-ios-get-started-button.md) > - [(Xamarin Android | Javascript)](./partner-xamarin-mobile-services-android-get-started-push button.md)

... will exist rendered similar this:

  • (iOS | .NET)
  • (iOS | JavaScript)
  • (Windows universal C# | .NET)
  • (Windows universal C# | Javascript)
  • (Windows Phone | .Cyberspace)
  • (Windows Telephone | Javascript)
  • (Android | .Internet)
  • (Android | Javascript)
  • (Xamarin iOS | Javascript)
  • (Xamarin Android | Javascript)

Subscript and superscript

You should but use subscript or superscript when necessary for technical accurateness, such equally when writing near mathematical formulas. Don't use them for non-standard styles, such as footnotes.

For both subscript and superscript, use HTML:

              Hullo <sub>This is subscript!</sub>

This renders every bit follows:

Hi This is subscript! 

              Good day <sup>This is superscript!</sup>

This renders as follows:

Cheerio This is superscript!

Tables

The simplest way to create a tabular array 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 elementary   |tabular array header| |----------|-----------|------------| |table     |information       |here        | |it doesn't|actually   |have to line up nicely!|

This renders as follows:

This is a simple table header
table data here
information technology doesn't really have to line up nicely!

You can marshal the columns past using colons:

              | Fun                  | With                 | Tables          | | :------------------- | -------------------: |:---------------:| | left-aligned column  | right-aligned column | centered cavalcade | | $100                 | $100                 | $100            | | $ten                  | $x                  | $x             | | $1                   | $1                   | $ane              |

Renders as follows:

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

Tip

The Docs Authoring Extension for VS Lawmaking makes it like shooting fish in a barrel to add basic Markdown tables!

Y'all tin can also utilize an online tabular array generator.

Line breaks inside words in any tabular array jail cell

Long words in a Markdown table might brand the table expand to the correct navigation and become unreadable. Yous tin can solve that by assuasive Docs rendering to automatically insert line breaks within words when needed. Just wrap up the table with the custom class [!div class="mx-tdBreakAll"].

Here is a Markdown sample of a table with three rows that will be wrapped by a div with the class name mx-tdBreakAll.

              > [!div class="mx-tdBreakAll"] > |Proper noun|Syntax|Mandatory for silent installation?|Clarification| > |-------------|----------|---------|---------| > |Tranquility|/quiet|Yes|Runs the installer, displaying no UI and no prompts.| > |NoRestart|/norestart|No|Suppresses any attempts to restart. By default, the UI will prompt earlier restart.| > |Assist|/help|No|Provides help and quick reference. Displays the right employ of the setup command, including a list of all options and behaviors.|

It will be rendered similar this:

Name Syntax Mandatory for silent installation? Description
Quiet /quiet Yes Runs the installer, displaying no UI and no prompts.
NoRestart /norestart No Suppresses whatsoever attempts to restart. By default, the UI volition prompt before restart.
Help /assist No Provides help and quick reference. Displays the correct utilize of the setup command, including a list of all options and behaviors.

Line breaks within words in 2nd column table cells

You might desire line breaks to be automatically inserted within words merely in the second column of a table. To limit the breaks to the second column, apply the grade mx-tdCol2BreakAll by using the div wrapper syntax as shown earlier.

Inconsistent column widths between tables

You may observe that the cavalcade widths of the tables in your articles wait odd or inconsistent. This behavior occurs because the length of text within the cells determines the layout of the table. Unfortunately, there's no manner 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 exist consequent, this would take some disadvantages besides:

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

Data matrix tables

A data matrix table has both a header and a weighted first column, creating a matrix with an empty jail cell in the pinnacle left. Docs has custom Markdown for data matrix tables:

              |                  |Header ane |Header ii| |------------------|---------|--------| |**Beginning cavalcade A**|Cell 1A  |Prison cell 2A | |**First cavalcade B**|Prison cell 1B  |Cell 2B |

The example renders as:

Header 1 Header 2
First cavalcade A Cell 1A Cell 2A
First column B Prison cell 1B Cell 2B

Every entry in the first column must be styled as bold (**bold**); otherwise the tables won't be attainable for screen readers or valid for Docs.

Tip

The Docs Authoring Pack for VS Lawmaking includes a function to catechumen a regular Markdown table into a data matrix table. Just select the table, right-click, and select Convert to information matrix table.

HTML Tables

HTML tables aren't recommended for Docs. They aren't human readable in the source - which is a key principle of Markdown.