Skip to content

Latest commit

 

History

History
257 lines (163 loc) · 7.43 KB

template.md

File metadata and controls

257 lines (163 loc) · 7.43 KB
Raw
title description author manager ms.date ms.topic ms.prod ms.service ms.technology ms.localizationpriority
ARTICLE TITLE | SERVICE NAME
GITHUB USERNAME
ALIAS
04/28/2016
conceptual
medium

Metadata and Markdown Template

This docs.ms template contains examples of markdown syntax, as well as guidance on setting the metadata. It is available in the root directory of each EM Pilot repository (e.g. ~/Azure-RMSDocs-pr /template.md) and is meant to be read as a markdown file, although you can refer to the published version to see how the markdown examples render.

When creating a markdown file you should copy the 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.

Metadata

The full metadata block is above, divided into required fields and optional fields; see the OPS metadata cheatsheet for more details. 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 commnted out, be sure to remove the #.
  • Colons in a value (e.g., a title) break the metadata parser. In their place, use the HTML encoding of : (e.g., "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 (e.g. see above). The title need not (and probably should not) 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.

Basic Markdown and GFM

All basic and Github-flavored markdown is supported. For more information on these, see:

Headings

Examples of first- and second-level headings are above.

There must be only one first-level heading 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.

Third-level heading

Fourth-level heading

Fifth level heading
Sixth-level heading

Text styling

Italics

Bold

Strikethrough

Links

To link to a markdown file in the same repo, use relative links.

To link to a header in the same markdown file, view the source of the published article, find the id of the head (e.g. id="blockquote", and link using # + id (e.g. #blockquote).

To link to a header in a markdown file in the same repo, use relative linking + hashtag linking.

To link to an external file, use the full URL as the link.

If a URL appears in a markdown file, it will be transformed into a clickable link.

Link priorities and examples

Link type Priority Example Lay example
File relative path 1st another-file.md
Root relative path 2nd ~/different-directory/another-file.md or ../different-directory/another-file.md
Site relative URL 3rd /windows/uwp/get-started/get-set-up
FQDN / Full URL Avoid https://doc.microsoft.com/help/contribute/links-how-to

Lists

Ordered lists

  1. This
  2. Is
  3. An
  4. Ordered
  5. List

Ordered list with an embedded list

  1. Here
  2. comes
  3. an
  4. embedded
    1. Miss Scarlett
    2. Professor Plum
  5. ordered
  6. list

Unordered Lists

  • This
  • is
  • a
  • bulleted
  • list

Unordered list with an embedded lists

  • This
  • bulleted
  • list
    • Mrs. Peacock
    • Mr. Green
  • contains
  • other
    1. Colonel Mustard
    2. Mrs. White
  • lists

Horizontal rule

Tables

Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
col 1 is default left-aligned $1

Code

Codeblock

{
   "aggregator": {
   "batchSize": 1000,
   flushTimeout": "00:00:30"
   }
}

In-line code

This is an example of in-line code.

Blockquotes

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.

Images

Static Image

:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This is the alt text.":::

Image with lightbox

:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This is the alt text." lightbox="memdocs/media/docs-github-edit.png":::

Animated gif

:::image type="content" source="memdocs/media/docs-filter-toc.gif" alt-text="This is the alt text.":::

Alerts

Note

Note

This is NOTE

Warning

Warning

This is WARNING

Tip

Tip

This is TIP

Caution

Caution

This is CAUTION

Important

Important

This is IMPORTANT

Videos

Channel 9

[!VIDEO http://channel9.msdn.com/Series/Azure-Active-Directory-Videos-Demos/Azure-Active-Directory-Connect-Express-Settings/player]

Youtube

[!VIDEO https://www.youtube.com/embed/R6_eWWfNB54]

docs.ms extensions

Button

[!div class="button"] button links

Selector

[!div class="op_single_selector"]

Step-By-Step

[!div class="step-by-step"] Pre Next