Markdown, Extensions, and HTML code
DocFX supports "DocFX Flavored Markdown" (DFM). It is 100% compatiable with GitHub Flavored Markdown, and adds some additional functionality, including cross reference and file inclusion.
Here are two great tutorials for Markdown and GitHub Flavored Markdown:
#Markdown editor
You can use any editor you like to edit Markdown. Some suggestions include: MarkdownPad, Visual Studio Code, Markdown Mode.
Most of them provide live preview functionality so that you can get an idea of what the rendered output will look like.
The following list represents the list of supported extensions in Open Publishing.
You can include other file parts into a documentation file. The included file has to be written in DFM syntax.
YAML headers are NOT supported when the file is referenced.
There are three types of file inclusion: inline, block, and image.
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 (within the repo).
The file path can be either an absolute file path or a relative file path.
<filepath> can be wrapped by ' or ".
For inline file inclusion, the file included will be considered as containing only inline tags - e.g.
###headerwill not be transformed because<h3>is a block tag, while[a](b)will be transformed to<a href='b'>a</a>because<a>is an inline tag.
...Other inline content... [!include[<title>](<filepath>)]
Block file inclusion must be in a single line and with no prefix characters before the start [. Content inside the included file will be transformed using DFM syntax.
[!include[<title>](<filepath>)]The syntax to include an image is ![[name]]({folderPath}) Example: 
Use specific syntax inside a block quote to indicate that the content following is a Note.
> [!NOTE]
> This is a NOTE
> [!WARNING]
> This is a WARNING
> [!TIP]
> This is a TIP
> [!IMPORTANT]
> This is IMPORTANT
And it will render like:
Anchor links allow you to go to a section of a specific topic.
Use the following syntax for the header you would like to link to:
## <a id="AnchorText"> </a> Header text
And the following for the link to it:
Go to [text](#AnchorText)
Example: Go to top
A user may need to define a section. This is mostly used for code tables. See the following example.
> [!div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar"]
> ```cs
> <cs code text>
> ```
> ```javascript
> <js code text>
> ```
The preceding blockquote markdown text will render as:
See Code snippets page.
See Metadata page.
You can embed HTML code into your content, as long as it is within the GitHub WhiteLlist. We also enable iframe element for video embedding even though it is not in the GFM whitelist. HTML rendered by the various markup language processors gets passed through an HTML sanitization filter for security reasons. HTML elements not in the whitelist are removed. HTML attributes not in the whitelist are removed from the preserved elements.
The following HTML elements, organized by category, are whitelisted:
| Type | Elements |
|---|---|
| Headings | h1, h2, h3, h4, h5, h6 |
| Prose | p, div, blockquote |
| Formatted | pre |
| Inline | b, i, strong, em, tt, code, ins, del, sup, sub, kbd, samp, q, var |
| Lists | ol, ul, li, dl, dt, dd |
| Tables | table, thead, tbody, tfoot, tr, td, th |
| Breaks | br, hr |
| Ruby (East Asian) | ruby, rt, rp |
| Video (not in GFM whitelist) | iframe |
| Comments | Comments |
The following attributes, organized by element, are whitelisted:
| Element | Attributes |
|---|---|
| a | href (http://, https://, mailto://, github-windows://, and github-mac:// URI schemes and relative paths only) |
| iframe | src, allowFullScreen, frameBorder, scrolling |
| img | src (http:// and https:// URI schemes and relative paths only) |
| div | itemscope, itemtype |
| All | abbr, accept, accept-charset, accesskey, action, align, alt, axis, border, cellpadding, cellspacing, char, charoff, charset, checked, cite, clear, cols, colspan, color, compact, coords, datetime, dir, disabled, enctype, for, frame, headers, height, hreflang, hspace, ismap, label, lang, longdesc, maxlength, media, method, multiple, name, nohref, noshade, nowrap, prompt, readonly, rel, rev, rows, rowspan, rules, scope, selected, shape, size, span, start, summary, tabindex, target, title, type, usemap, valign, value, vspace, width, itemprop |
Note that the id attribute is not whitelisted.