Markdown Support

Markdown is a plain text format used to write structured documents. The help file builder supports CommonMark compliant Markdown and uses the Markdig processor to handle topic conversion. The following Markdig extensions are enabled and available for use in topics:

• YAML Header - This is used to specify topic metadata such as the title and keywords. See below for more information.
• Abbreviations
• Alert Blocks - The help file builder provides some additional features. See below for more information.
• Auto-Identifiers
• Auto-Links
• Citations
• Custom Containers
• Definition Lists
• Emojis
• Emphasis Extras
• Figures - The help file builder provides some additional features. See below for more information.
• Footers
• Footnotes
• Generic Attributes - This is used to add generic attributes to any element. See below for more information on common usage.
• Grid Tables
• List Extras
• Media Links - Note that this is not the same thing as a MAML media link element. This is used specifically to embed links to videos.
• Pipe Tables
• Referral Links - This is used to add rel="noopener noreferrer" to all anchor links in Markdown topics to match the behavior of the anchor links generated by the presentation styles.
• Task Lists

Note that when used with the help file builder, Markdown topics support the use of HTML as well as MAML elements. As such, if the Markdown syntax does not meet your needs for more complex content, you can fall back to the equivalent HTML or MAML elements to generate the same output. The help file builder also supports rendering Markdown content nested within MAML or HTML elements. This allows you to use the more structured elements for such things as tables while still using Markdown for the content. See the section below for more information on how to make this work.

Also referred to as YAML Front Matter, this header is used to specify topic metadata such as the title and keywords. The header must appear at the very beginning of the file and be enclosed within triple dashes. For example:

---
uid: UniqueTopicID
title: The Topic Title
tocTitle: Optional Title for the Table of Contents
linkText: Optional Text to Use For Links
keywords: keyword, term 1, term 2, "term, with comma"
alt-uid: OptionalAlternateID
summary: Optional summary abstract
# Lines prefixed with a pound sign are considered comments and are ignored.
---
The topic content appears after the YAML header.

If the YAML header is omitted or any of the properties are missing, the help file builder will assume default values based on the property as indicated below.

uid

The unique identifier for the topic. If omitted, the unique ID will be generate based on the title, TOC title, or link text, or in the absence of those, the topic filename. It is recommended that you always specify a unique ID for each topic to ensure that it remains constant even if the title or filename changes.

title

The topic title. If omitted, the title will be derived from the TOC title, link text, or in the absence of those, the first section header title if there is one or the filename if not.

tocTitle

An optional title to use in the table of contents. If omitted, the TOC title will be derived from the title. In some cases, the title may not be appropriate for the table of contents or is too long to be practical. In such cases you can specify shorter or more appropriate text for the table of contents via this property.

linkText

An optional title to use for links to the topic. If omitted, the link text will be derived from the title. In some cases the title may not be appropriate or may be too long to be practical for links that refer to the topic. In such cases you can specify shorter or more appropriate text for the link via this property. This saves you from having to specify the shorter inner text on each link that uses the topic ID.

keywords

Optional keywords for the topic. Multiple keywords should be separated by commas. Keywords that contain commas should be enclosed in double quotes. This property only has use for the Help 1 (CHM) and MS Help Viewer (MSHC) output formats. They are ignored for website and Open XML presentation styles.

alt-uid

This can be used to specify an alternate ID for the topic. This is useful when you want to change the topic ID but still want existing links in other topics that use the old ID to continue to work. It is mainly used when converting MAML topics to Markdown and you enable the option to switch to using the filenames for the unique IDs.

summary

This is equivalent to the MAML summary element when the abstract="true" attribute is used. The summary is added as a Description metadata element to the HTML header section.

IDs are automatically generated for section titles in Markdown topics using the Auto-Identifiers extension. Other in-page link targets can be created by using the attribute syntax to add an ID to a block of text or an element.

{id="intro"}
The attribute above adds a link ID to a block of text such as the introduction paragraph.

Term 8 {id="Term8"}
:   Definition 8.  The entry's term has an `id` attribute that can be used as a link target.

<table>
  <tr>
    <td id="Table1Cell1">The cell has an `id` attribute that can be used as a link target</td>
  </tr>
</table>

To create links to other topics within the documentation, use the standard Markdown link syntax with the topic ID as the link target prefixed with an @ character to indicate that it is a topic ID rather than a URL. The unique ID or alternate ID can be used as the link target. If no link text is specified, the topic title will be used. To link to a specific section, append a # followed by the section ID to the target. For in-page links, just specify the pound sign followed by the section ID. Some examples are shown below.

Standard link using the topic title as the link text: [](@RelatedTopic)
With inner text: [alternate text for the link](@RelatedTopic)
In-page link to introduction: [Back to Intro](#intro)
Link to a section in another topic: [](@OtherResources#Tools)

To display images in Markdown topics, use the standard Markdown image syntax with an image ID (). The image ID is prefixed with an @ character to indicate that it is an image ID rather than a URL. The image ID should correspond to a file in the project with its Build Action set to Image that has a matching ID. This is equivalent to the MAML mediaLinkInline element. If no alternate text is specified, the alternate text from the project file properties will be used if any is specified there.

The Markdig Figure extension can be used to display block images similar to the MAML mediaLink element. The help file builder adds support for placement and a figure caption to match the MAML element. To specify the placement, use the {placement="value"} attribute on the opening ^^^ marker where value is near (left aligned), center (centered alignment), or far (right aligned). A caption can be specified by adding text after the opening or closing ^^^ marker. If used on the opening marker, add the text before the placement attribute if it is specified as well. For example:

<!-- No caption, default near (left-aligned) image placement -->
^^^
![](@ImageId)
^^^

<!-- Caption before, centered image -->
^^^ Caption Before {placement="center"}
![](@ImageId)
^^^

<!-- Caption after, far (right-aligned) image alignment -->
^^^ {placement="far"}
![](@ImageId)
^^^ Figure 1: Caption after with lead-in

To link to code entity topics such as types or API members in Markdown topics, use standard Markdown link syntax with the API member ID as the link target prefixed with an @ character to indicate that it is a code entity rather than a URL. The following attributes can be used to modify the link behavior:

show-container="true"

By default namespaces and type names are omitted from the link text for code entities. By adding this attribute, you can include the container name in the link text. For types, this adds the namespace. For API members, it adds the type name. If inner text is specified for the link, this option will be ignored.

show-parameters="true"

By default, methods omit the parameters in the link text. By adding this attribute, you can include the parameters in the link text. If inner text is specified for the link or the link is to an overload topic, this option will be ignored.

prefer-overload="true"

Adding this attribute to method code entity references will cause the link to go to the overloads topic for the method if there are multiple versions of the method. If omitted or if there are no overloads, the link will go to the indicated member topic instead.

The Entity References Window can be used to easily find and insert code entity reference links in the proper format. Some examples are shown below:

[](@T:System.IO.FileStream){show-container="true"}
[](@M:System.IO.FileStream.#ctor(System.String,System.IO.FileMode)){show-container="true" prefer-overload="true"}
[](@M:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)){show-container="true" show-parameters="true"}
[](@P:System.IO.FileStream.Length)
[](@M:System.IO.FileStream.Flush){prefer-overload="true"}
[FileStream.Flush on Microsoft Docs](@M:System.IO.FileStream.Flush)

Markdown alert blocks can be used to create alerts similar to the MAML alert element or the XML comments note element. The help file builder supports using any of the alert or note class types as the alert block type. The block type is case-insensitive. In addition, a custom title can be specified for the alert block by adding it after the block type separated by a comma. Some example are shown below:

> [!NOTE]
> This is a note

> [!caution]
> The block type value is case-insensitive.

> [!SECURITY]
> Do not tape your password to the underside of your keyboard.

> [!CS]
> This could contain C#-specific usage notes.

> [!TODO]
> This could contain a To Do list.

> [!TODO, Project Road Map]
> This alert contains a custom title.

The help file builder supports all of the same extension attributes on fenced code blocks as it does in MAML topics when using the code element. Use the attribute syntax after the opening fence to specify the attributes. Note that the language attribute is not used. Instead, the language appears immediately after the back ticks for the fenced code block. If code blocks are nested within a fenced code block to import code, use the MAML code element to import the nested regions. An example is show below. See the Code Block Component topic for more information on the available attributes and their usage.

``` csharp {title="Example Code"}

... example code ...

```

``` csharp {title="Imported code block" source="..\Example.cs" region="ExampleRegion"}
```

``` vb {title="Nested code imports"}
<code source="..\Class1.vb" region="Snippet #1" />

' ... Some stuff happens here ...

<code source="..\Class1.vb" region="Snippet #2" />
```

To match the behavior of the MAML languageKeyword element, prefix the keyword with a colon and enclose it in back ticks. Recognized language keywords will then change based on the language filter.

To match the behavior of the `languageKeyword` MAML element, use this format for
language keywords: `:null`, `:Nothing`, `:Shared`, `:async/await`

Markdown does not have a "no bullet" list style like MAML. However, by applying the style using the attribute syntax, you can get the same effect. A blank line should precede the attribute to ensure that it is applied correctly to the following list items. For example:

- Bullet item

  {class="noBullet"}
  - No bullet item 1
  - No bullet item 2
  - No bullet item 3
- Bullet item 2

Normal Markdown files do not render Markdown nested within HTML elements. However, the help file builder takes steps to allow this to happen. Markdown nested within MAML or HTML elements that appears in Markdown files will typically be rendered. However, it may be necessary to insert an extra blank line before and after the Markdown content in the element that contains it so that it is handled correctly. The end tag should also be flush left with no leading spaces. For example:

Content *before* the table.

<table>
  <tr>
    <th>Header 1</th>
    <th>Header 2</th>
    <th>Header 3</th>
  </tr>
  <tr>
    <td id="Table1Cell1">

Put a **leading blank line** after the opening tag, no spaces.

Another **paragraph**.  Put a blank line before the closing tag and make sure
it is flush left.

</td>
    <td>

Cell _2_

Para _2_

</td>
    <td>Cell 3</td>
  </tr>
</table>

Content *after* the table.

Other Resources
Conceptual and Additional Content
Conceptual Content