| title | description | keywords | author | manager | ms.date | ms.topic | ms.prod | ms.service | ms.technology | ms.assetid | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
04/28/2016 |
article |
|
This docs.ms template contains examples of Markdown syntax, as well as guidance on setting the metadata. To get the most of it, you must view both the raw Markdown and the rendered view (for instance, the raw Markdown shows the metadata block, while the rendered view does not).
When creating a Markdown file, you should copy this template to a new file, fill out the metadata as specified below, set the H1 heading above to the title of the article, and delete the content.
The full metadata block is above (in the raw Markdown), divided into required fields and optional fields. Some key notes:
- You must have a space between the colon (:) and the value for a metadata element.
- If an optional metadata element does not have a value, comment out the element with a # (do not leave it blank or use "na"); if you are adding a value to an element that was commented out, be sure to remove the #.
- Colons in a value (for example, a title) break the metadata parser. In their place, use the HTML encoding for a colon of
:(for example,"title: Azure Rights Management: the basics | Azure RMS"). - title: This title will appear in search engine results. The title should end with a pipe (|) followed by the name of the service (for example, see above). The title doesn't need (and probably shouldn't) be identical to the title in your H1 heading. It should be roughly 65 characters (including | SERVICE NAME)
- author, manager, reviewer: The author field should contain the GitHub username of the author, not their alias. The "manager" and "reviewer" fields, on the other hand, should contain aliases. ms.reviewer specifies the name of the PM associated with the article or service.
- ms.assetid: This is the GUID of the article from CAPS. When creating a new Markdown file, get a GUID from https://www.guidgenerator.com.
- ms.prod, ms.service, ms.technology, ms.devlang, ms.topic, ms.tgt_pltfrm: Possible values for these elements can be found here.
All basic and GitHub-flavored Markdown is supported. For more information on these, see:
Markdown uses special characters such as *, `, and # for formatting. If you wish to include one of these characters in your content, you must do one of two things:
- Put a backslash before the special character to "escape" it (for example, \* for a *)
- Use the HTML entity code for the character (for example, * for a *).
Headings should be done using atx-style, that is, use 1-6 hash characters (#) at the start of the line to indicate a heading, corresponding to HTML headings levels H1 through H6. Examples of first- and second-level headers are used above.
There must be only one first-level heading (H1) in your topic, which will be displayed as the on-page title.
Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title.
Italics
Bold
Strikethrough
To link to a header in the same Markdown file, view the source of the published article, find the id of the head (for example, id="blockquote"), and link using # + id (for example, #blockquote).
- Example: Blockquotes
To link to a Markdown file in the same repo, use relative links, including the ".md" at the end of the filename.
- Example: Readme file
- Example: Tools and setup for contributors
To link to a header in a Markdown file in the same repo, use relative linking + hashtag linking.
- Example: Permissions in GitHub
To link to an external file, use the full URL as the link.
- Example: GitHub
If a URL appears in a Markdown file, it will be transformed into a clickable link.
- Example: http://www.github.com
- This
- Is
- An
- Ordered
- List
- Here
- comes
- an
- embedded
- Miss Scarlett
- Professor Plum
- ordered
- list
- This
- is
- a
- bulleted
- list
- This
- bulleted
- list
- Mrs. Peacock
- Mr. Green
- contains
- other
- Colonel Mustard
- Mrs. White
- lists
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| col 1 is default | left-aligned | $1 |
Indent code four spaces for generic codeblock coding.
function fancyAlert(arg) {
if(arg) {
$.docs({div:'#foo'})
}
}
Use three backticks (```) + a language ID to apply language-specific color coding to a code block. Here is the entire list of GitHub Flavored Markdown (GFM) language IDs.
using System;
namespace HelloWorld
{
class Hello
{
static void Main()
{
Console.WriteLine("Hello World!");
// Keep the console window open in debug mode.
Console.WriteLine("Press any key to exit.");
Console.ReadKey();
}
}
}friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
print "iteration {iteration} is {name}".format(iteration=i, name=name)Clear-Host
$Directory = "C:\Windows\"
$Files = Get-Childitem $Directory -recurse -Include *.log `
-ErrorAction SilentlyContinueUse backticks (`) for inline code.
The drought had lasted now for ten million years, and the reign of the terrible lizards had long since ended. Here on the Equator, in the continent which would one day be known as Africa, the battle for existence had reached a new climax of ferocity, and the victor was not yet in sight. In this barren and desiccated land, only the small or the swift or the fierce could flourish, or even hope to survive.
Note
This is NOTE
Warning
This is WARNING
Tip
This is TIP
Important
This is IMPORTANT
Doc.ms provides a few extensions to GitHub Flavored Markdown.
You can embed the Markdown of one file into another using an include.
[!INCLUDEsample include file]
[!div class="button"] button links
[!div class="op_single_selector"]