DocFX Flavored Markdown

DocFX supports DocFX Flavored Markdown, or DFM. It supports all GitHub Flavored Markdown syntax with 2 exceptions when resolving list. Also, DFM adds new syntax to support additional functionalities, including cross reference and file inclusion.

Yaml Header

Yaml header in DFM is considered as the metadata for the Markdown file. It will transform to yamlheader tag when processed. Yaml header MUST be the first thing in the file and MUST take the form of valid YAML set between triple-dashed lines. Here is a basic example:

---
uid: A.md
title: A
---

Cross Reference

Cross reference allows you to link to another topic by using its unique identifier (called UID) instead of using its file path.

For conceptual Markdown files UID can be defined by adding a uid metadata in YAML header:

---
uid: uid_of_the_file
---

This is a conceptual topic with `uid` specified.

For reference topics, UIDs are auto generated from source code and can be found in generated YAML files.

You can use one of the following syntax to cross reference a topic with UID defined:

Markdown link: [link_text](xref:uid_of_the_topic)
Auto link: <xref:uid_of_the_topic>
Shorthand form: @"uid_of_the_topic"

All will render to:

<a href="url_of_the_topic">link_text</a>

If link_text is not specified, DocFX will extract the title from the target topic and use it as the link text.

Note

Hashtag in xref is always treated as separator between file name and anchor name. That means if you have # in UID, it has to be encoded to %23.

Actually xref format follows URI standard so all reserved characters should be encoded.

For more information, see cross reference.

File Inclusion

DFM adds syntax to include other file parts into current file, the included file will also be considered as in DFM syntax.

There are two types of file inclusion: Inline and block, as similar to inline code span and block code.

Note

YAML header is NOT supported when the file is an inclusion.

Inline

Inline file inclusion is in the following syntax, in which <title> stands for the title of the included file, and <filepath> stands for the file path of the included file. The file path can be either absolute or relative.<filepath> can be wrapped by ' or ".

Note

For inline file inclusion, the file included will be considered as containing only inline tags, for example, ### header inside the file will not transfer since <h3> is a block tag, while [a](b) will transform to <a href='b'>a</a> since <a> is an inline tag. Also, ending white spaces will be trimmed, considering ending white spaces in inline inclusion in most cases are typos.

...Other inline contents... [!include[<title>](<filepath>)]

Block

Block file inclusion must be in a single line and with no prefix characters before the start [. Content inside the included file will transform using DFM syntax.

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

Section definition

User may need to define section. Mostly used for code table. Give an example below.

> [!div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar"]
> ```cs
> <cs code text>
> ```
> ```javascript
> <js code text>
> ```

The above blockquote Markdown text will transform to section html as in the following:

<div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar">
  <pre><code>cs code text</code></pre>
  <pre><code>js code text</code></pre>
</div>

Code Snippet

Allows you to insert code with code language specified. The content of specified code path will expand.

[!code-<language>[<name>](<codepath><queryoption><queryoptionvalue> "<title>")]

<language> can be made up of any number of character and '-'. However, the recommended value should follow Highlight.js language names and aliases.
<codepath> is the relative path in file system which indicates the code snippet file that you want to expand.
<queryoption> and <queryoptionvalue> are used together to retrieve part of the code snippet file in the line range or tag name way. We have 2 query string options to represent these two ways:

	query string using `#`	query string using `?`
1. line range	`#L{startlinenumber}-L{endlinenumber}`	`?start={startlinenumber}&end={endlinenumber}`
2. tagname	`#{tagname}`	`?name={tagname}`
3. multiple region range	Unsupported	`?range={rangequerystring}`
4. highlight lines	Unsupported	`?highlight={rangequerystring}`
5. dedent	Unsupported	`?dedent={dedentlength}`

In ? query string, the whole file will be included if none of the first three option is specified.
If dedent isn't specified, the maximum common indent will be trimmed automatically.
<title> can be omitted.

Code Snippet Sample

[!code-csharp[Main](Program.cs)]

[!code[Main](Program.cs#L12-L16 "This is source file")]
[!code-vb[Main](../Application/Program.vb#testsnippet "This is source file")]

[!code[Main](index.xml?start=5&end=9)]
[!code-javascript[Main](../jquery.js?name=testsnippet)]
[!code[Main](index.xml?range=2,5-7,9-) "This includes the lines 2, 5, 6, 7 and lines 9 to the last line"]
[!code[Main](index.xml?highlight=2,5-7,9-) "This includes the whole file with lines 2,5-7,9- highlighted"]

Tag Name Representation in Code Snippet Source File

DFM currently supports the following <language> values to be able to retrieve by tag name:

C family
- Start with: // <{name}>
- End with: // </{name}>
- Languages: actionscript, arduino, assembly (alias: nasm), c (alias: cpp, c++, objective-c, obj-c, objc, objectivec), csharp (alias: cs), cshtml, cuda, d (alias: dlang), fsharp (alias: fs), go (alias: golang), java, javascript (alias: js, node), pascal, php, processing, rust, scala, smalltalk, swift, typescript (alias: ts)
- File extensions: .as, .asm, .ino, .c, .cc, .cpp, .cs, .cshtml .cu, .cuh, .d, .fs, .fsi, .fsx, .go, .h, .hpp, .java, .js, .pas, .php, .pde, .rs, .scala, .st, .swift, .ts
Basic family
- Start with: ' <{name}>
- End with: ' </{name}>
- Languages: vb, vbhtml, vbnet, vbscript
- File extensions: .bas, .vb, .vba, .vbhtml, .vbs
Markup language family
- Start with: 
- End with: 
- Languages: cshtml, html, vbhtml, wsdl, xml, xsl, xslt, xsd, xaml
- File extensions: .asp, .aspx, .csdl, .cshtml, .edmx, .jsp, .vbhtml, .wsdl, .xaml, .xml, .xsd, .xsl, .xslt, .html
Sql family
- Start with: -- <{name}>
- End with: -- </{name}>
- Languages: sql
- File extensions: .sql
Script family
- Start with: # <{name}>
- End with: # </{name}>
- Languages: perl, powershell (alias: posh), python, r, ruby (alias: ru), shell (alias: sh, bash)
- File extensions: .bash, .pl, .ps1, .py, .r, .ru, .ruby, .sh
Special language
- batchfile
  - Start with: rem <{name}>
  - End with: rem </{name}>
  - Languages: batchfile
  - File extensions: .bat .cmd
- csharp
  - Start with: #region {name}
  - End with: #endregion
  - Languages: csharp (alias: cs)
  - File extensions: .cs .cshtml
- erlang
  - Start with: % <{name}>
  - End with: % </{name}>
  - Languages: erlang
  - File extensions: .erl
- haskell
  - Start with: -- <{name}>
  - End with: -- </{name}>
  - Languages: haskell
  - File extensions: .hs
- matlab
  - Start with: % <{name}>
  - End with: % </{name}>
  - Languages: matlab
  - File extensions: .matlab
- lisp
  - Start with: ; <{name}>
  - End with: ; </{name}>
  - Languages: lisp
  - File extensions: .lisp, .lsp
- lua
  - Start with: -- <{name}>
  - End with: -- </{name}>
  - Languages: lua
  - File extensions: .lua
- vb
  - Start with: #Region {name}
  - End with: #End Region
  - Languages: vb (alias: vbnet)
  - File extensions: .vb .vbhtml

Note

If dev-lang is not specified, file extension will be used to determine the language.

Note (Warning/Tip/Important)

Using specific syntax inside block quote to indicate the following content is Note.

> [!NOTE]
> <note content>
> [!WARNING]
> <warning content>

The above content will be transformed to the following html:

<div class="NOTE">
  <h5>NOTE</h5>
  <p>note content</p>
</div>
<div class="WARNING">
  <h5>WARNING</h5>
  <p>WARNING content</p>
</div>

Here are all the supported note types with the styling of the default theme applied:

Note

This is a note which needs your attention, but it's not super important.

[!TIP] This is a note which needs your attention, but it's not super important.

[!WARNING] This is a warning containing some important message.

[!IMPORTANT] This is a warning containing some important message.

[!CAUTION] This is a warning containing some important message.

Tabbed content

Syntax

Start a tab by a special markdown title (any level).
- Title content should be a markdown link.
- Link target is #tab/{tabid} or #tab/{tabid}/{condition}
Continue by any other content.
End by a markdown hr.

Example

Tab group 1:

# [Tab Text 1](#tab/tabid-1)

Tab content-1-1.

# [Tab Text 2](#tab/tabid-2)

Tab content-2-1.

***

Tab group 2:

# [Tab Text A](#tab/tabid-a)

Tab content-a-1.

# [Tab Text B](#tab/tabid-b)

Tab content-b-1.

***

Tab group 3:

# [Tab Text 1](#tab/tabid-1)

Tab content-1-1.

# [Tab Text 2](#tab/tabid-2)

Tab content-2-1.

***

Tab group 4:

# [Tab Text A](#tab/tabid-a)

Tab content-a-2.

# [Tab Text B](#tab/tabid-b)

Tab content-b-2.

***

The result will be:

Tab group 1:

Tab Text 1

Tab content-1-1.

Tab Text 2

Tab content-2-1.

Tab group 2:

Tab Text A

Tab content-a-1.

Tab Text B

Tab content-b-1.

Tab group 3:

Tab Text 1

Tab content-1-1.

Tab Text 2

Tab content-2-1.

Tab group 4:

Tab Text A

Tab content-a-2.

Tab Text B

Tab content-b-2.

Behavior

Tab groups with a same set of id are linkable in one page.

In example, tab group 1, 3 have same id set: tabid-1, tabid-2, tab group 2, 4 have same id set: tabid-a, tabid-b.

So tab group 1, 3 are linked, tab group 2, 4 are linked. When tab tabid-1 in tab group 1 is clicked, tab tabid-1 in tab group 3 will be selected in same time. But tab group 2, 4 do not have any changed.

Condition

Condition is the tab id of other table groups.

e.g.:

Tab Group 1:

# [Tab Text 1](#tab/tabid-1)

Tab content-1.

# [Tab Text 2](#tab/tabid-2)

Tab content-2.

***

Tab Group 2:

# [Tab Text A](#tab/tabid-a/tabid-1)

Tab content-a for 1.

# [Tab Text A](#tab/tabid-a/tabid-2)

Tab content-a for 2.

# [Tab Text B](#tab/tabid-b/tabid-1)

Tab content-b for 1.

# [Tab Text B](#tab/tabid-b/tabid-2)

Tab content-b for 2.

***

Result:

Tab Group 1:

Tab Text 1

Tab content-1.

Tab Text 2

Tab content-2.

Tab Group 2:

Tab Text A

Tab content-a for 1.

Tab Text A

Tab content-a for 2.

Tab Text B

Tab content-b for 1.

Tab Text B

Tab content-b for 2.

When select tabid-1 in tab group 1, you can get content-a or content-b for 1 in group 2.
When select tabid-2 in tab group 1, you can get content-a or content-b for 2 in group 2.

Differences between DFM and GFM

List

DFM list item always uses the first character in the first line to decide whether it is in the list item, but GFM does not.
For example:

Case 1:

* a
  * b
    * c

  text

a starts at column 3, b starts at column 5, c starts at column 7.

`text` will be	in DFM, `text` starts at column	in GFM, `text` starts at column
paragraph	1	1
part of item a	2 ~ 3 (> 1 and <= 3)	2 ~ 4
part of item b	4 ~ 5 (> 3 and <= 6)	5 ~ 6
part of item c	6 or more (> 6)	7 or more
part of item c and code	11 (7 + 4)	13

Case 2:

1. a
   2. b
      3. c

   text

a starts at column 4, b starts at column 7, c starts at column 10.

`text` will be	in DFM, `text` starts at column	in GFM, `text` starts at column
paragraph	1	1
part of item a	2 ~ 4 (> 1 and <= 4)	2 ~ 4
part of item b	5 ~ 7 (> 4 and <= 7)	5 ~ 8
part of item c	8 or more (> 7)	9 or more
part of item c and code	14 (10 + 4)	15

List after paragraph

In GFM, list after paragraph must be separated by two or more new line character.
In DFM, one new line also works.

For example:

text
1. a
2. b

In GFM, it will be rendered as one paragraph with content text 1. a 2. b.
In DFM, it will be rendered as a paragraph (with content text) and a list.

Differences introduced by DFM syntax

Warning

Please note that DFM introduces more syntax to support more functionalities. When GFM does not support them, preview the Markdown file inside GFM Preview can lead to different results.

YAML header

In GFM, YAML header must start at the very beginning of the Markdown file. In DFM, YAML header contains more powerful meanings. Refer to Yaml Header for details.

...some text...

---
a: b
---

In GFM, it would be rendered as <hr>a: b<hr>.
In DFM, it would be rendered as a YAML header.

If you want to get <hr> in html in DFM, please use:

- - -
***
* * *

or change content to make it not in YAML format:

---
a\: b
---

Text after block extension

Some block extension in DFM cannot be recognized in GFM. In GFM, it would be treated as a part of paragraph. Then, following content would be treated as a part of paragraph.

For example:

> [!NOTE]
>     This is code.

In GFM, it will be rendered as a paragraph with content [!NOTE] This is code. in blockquote.
In DFM, it will be rendered as a code in note.

Files

docfx_flavored_markdown.md

Latest commit

History

docfx_flavored_markdown.md

File metadata and controls

DocFX Flavored Markdown

Yaml Header

Cross Reference

File Inclusion

Inline

Block

Section definition

Code Snippet

Code Snippet Sample

Tag Name Representation in Code Snippet Source File

Note (Warning/Tip/Important)

Tabbed content

Syntax

Example

Behavior

Condition

Differences between DFM and GFM

List

List after paragraph

Differences introduced by DFM syntax

YAML header

Text after block extension