Docs: Convert document Overviews and Best Practices to markdown

.github/CODEOWNERS

@@ -86,7 +86,7 @@ OverflowSet/  @micahgodbolt
 # Overlay/
 # Panel/
 # Persona/
-Persona/PersonaCoin.tsx @mtennoe @jakob101
+Persona/PersonaCoin/ @mtennoe @jakob101
 Persona/PersonaConsts.tsx @mtennoe @jakob101
 pickers/  @joschect
 # Pivot/
@@ -105,4 +105,59 @@ TeachingBubble/   @micahgodbolt
 Toggle/  @phkuo
 Tooltip/  @micahgodbolt
 
+## Docs
+# ActivityItem/docs/
+# Breadcrumb/docs/
+# Button/docs/
+Calendar/docs/   @lorejoh12 @sathi23
+Callout/docs/  @joschect
+# Check/docs/
+# Checkbox/docs/
+ChoiceGroup/docs/   @srideshpande
+# ColorPicker/docs/
+# ComboBox/docs/
+CommandBar/docs/   @micahgodbolt
+ContextualMenu/docs/  @joschect
+DatePicker/docs/   @lorejoh12 @sathi23
+# DetailsList/docs/
+# Dialog/docs/
+DocumentCard/docs/ @yiminwu @mikewheaton
+# Dropdown/docs/
+# Fabric/docs/
+# FacePile/docs/
+# FocusTrapZone/docs/
+# FocusZone/docs/
+GroupedList/docs/  @aditima
+HoverCard/docs/   @atneik @Jahnp
+# Icon/docs/
+# Image/docs/
+# Label/docs/
+Layer/docs/  @ThomasMichon
+# Link/docs/
+List/docs/  @cschleiden
+# MarqueeSelection/docs/
+# MessageBar/docs/
+# Modal/docs/
+# Nav/docs/
+OverflowSet/docs/  @micahgodbolt
+# Overlay/docs/
+# Panel/docs/
+# Persona/docs/
+pickers/docs/  @joschect
+# Pivot/docs/
+# Popup/docs/
+# ProgressIndicator/docs/
+Rating/docs/  @cschleiden
+ResizeGroup/docs/  @micahgodbolt
+# SearchBox/docs/
+# Slider/docs/
+# SpinButton/docs/
+# Spinner/docs/
+# SwatchColorPicker/docs/
+TeachingBubble/docs/   @micahgodbolt
+# TextField/docs/
+# Theme/docs/
+Toggle/docs/  @phkuo
+Tooltip/docs/  @micahgodbolt
+
 

common/changes/@uifabric/example-app-base/docs-convert-to-markdown_2018-04-16-23-02.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@uifabric/example-app-base",
+      "comment": "Fix code block line-height",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@uifabric/example-app-base",
+  "email": "[email protected]"
+}

common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-14-00-37.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@uifabric/styling",
+      "comment": "Add opt-in @deprecated comments",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@uifabric/styling",
+  "email": "[email protected]"
+}

common/changes/@uifabric/styling/docs-convert-to-markdown_2018-04-16-23-02.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@uifabric/styling",
+      "comment": "Fix deprecated semantic slots returning empty strings",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@uifabric/styling",
+  "email": "[email protected]"
+}

common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-11-23-54.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Convert documentation to markdown for HIG.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "[email protected]"
+}

common/changes/office-ui-fabric-react/docs-convert-to-markdown_2018-04-14-00-37.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Revamp Themes documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "[email protected]"
+}

packages/example-app-base/src/components/templates/TypeScriptSnippet.tsx

@@ -13,10 +13,11 @@ registerLanguage('typescript', ts);
 export const rootClass = mergeStyles({
   overflowY: 'auto',
   maxHeight: '400px',
+  display: 'flex',
   selectors: {
     'code': {
       fontFamily: 'Monaco, Menlo, Consolas, "Droid Sans Mono", "Inconsolata", "Courier New", monospace',
-      lineHeight: 19
+      lineHeight: '1.6'
     }
   }
 });
@@ -28,7 +29,7 @@ export const lineNumberStyle = {
   display: 'block',
   borderRight: '1px solid #666',
   paddingRight: 4,
-  lineHeight: '19px'
+  lineHeight: 'inherit',
 };
 
 export class TypeScriptSnippet extends React.Component {

packages/office-ui-fabric-react/src/components/ActivityItem/ActivityItemPage.tsx

@@ -22,7 +22,7 @@ export class ActivityItemPage extends React.Component<IComponentDemoPageProps, {
       <ComponentPage
         title='ActivityItem'
         componentName='ActivityItem'
-        componentUrl='https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/office-ui-fabric-react/src/components/ActivityItem/'
+        componentUrl='https://github.com/OfficeDev/office-ui-fabric-react/tree/master/packages/office-ui-fabric-react/src/components/ActivityItem'
         exampleCards={
           <div>
             <ExampleCard title='Activity Items with Icons' code={ ActivityItemBasicExampleCode }>

packages/office-ui-fabric-react/src/components/Breadcrumb/BreadcrumbPage.tsx

@@ -3,7 +3,8 @@ import {
   ExampleCard,
   IComponentDemoPageProps,
   ComponentPage,
-  PropertiesTableSet
+  PropertiesTableSet,
+  PageMarkdown,
 } from '@uifabric/example-app-base';
 
 import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus';
@@ -24,6 +25,7 @@ export class BreadcrumbPage extends React.Component<IComponentDemoPageProps, any
       <ComponentPage
         title='Breadcrumb'
         componentName='BreadcrumbExample'
+        componentUrl='https://github.com/OfficeDev/office-ui-fabric-react/tree/master/packages/office-ui-fabric-react/src/components/Breadcrumb'
         exampleCards={
           <div>
             <ExampleCard
@@ -48,32 +50,27 @@ export class BreadcrumbPage extends React.Component<IComponentDemoPageProps, any
           />
         }
         overview={
-          <div>
-            <p>Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy and help the user understand where they are in relation to the rest of that hierarchy. They also afford one-click access to higher levels of that hierarchy.</p>
-            <p>Breadcrumbs are typically placed, in horizontal form, under the masthead or navigation of an experience, above the primary content area.</p>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md') }
+          </PageMarkdown>
         }
         bestPractices={
           <div />
         }
         dos={
-          <div>
-            <ul>
-              <li>Place Breadcrumbs at the top of a page, above a list of items, or above the main content of a page.</li>
-            </ul>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md') }
+          </PageMarkdown>
         }
         donts={
-          <div>
-            <ul>
-              <li>Don't use Breadcrumbs as a primary way to navigate an app or site.</li>
-            </ul>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md') }
+          </PageMarkdown>
         }
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={
           <ComponentStatus
-            {...BreadcrumbStatus}
+            { ...BreadcrumbStatus }
           />
         }
       />

packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDonts.md

@@ -0,0 +1 @@
+- Don't use Breadcrumbs as a primary way to navigate an app or site.

packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbDos.md

@@ -0,0 +1 @@
+- Place Breadcrumbs at the top of a page, above a list of items, or above the main content of a page.

packages/office-ui-fabric-react/src/components/Breadcrumb/docs/BreadcrumbOverview.md

@@ -0,0 +1,3 @@
+Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy and help the user understand where they are in relation to the rest of that hierarchy. They also afford one-click access to higher levels of that hierarchy.
+
+Breadcrumbs are typically placed, in horizontal form, under the masthead or navigation of an experience, above the primary content area.

packages/office-ui-fabric-react/src/components/Button/ButtonPage.tsx

@@ -3,7 +3,8 @@ import {
   ExampleCard,
   IComponentDemoPageProps,
   ComponentPage,
-  PropertiesTableSet
+  PropertiesTableSet,
+  PageMarkdown,
 } from '@uifabric/example-app-base';
 import { ButtonStatus } from './Button.checklist';
 import { ButtonDefaultExample } from './examples/Button.Default.Example';
@@ -18,7 +19,6 @@ import { ButtonSwapExample } from './examples/Button.Swap.Example';
 import { ButtonSplitExample, ButtonSplitCustomExample } from './examples/Button.Split.Example';
 import { ComponentStatus } from '../../demo/ComponentStatus/ComponentStatus';
 import { Checkbox } from 'office-ui-fabric-react/lib/Checkbox';
-import { Link } from '../../Link';
 import * as exampleStylesImport from '../../common/_exampleStyles.scss';
 const exampleStyles: any = exampleStylesImport;
 
@@ -70,8 +70,9 @@ export class ButtonPage extends React.Component<IComponentDemoPageProps, IButton
   public render() {
     return (
       <ComponentPage
-        title={ 'Button' }
+        title='Button'
         componentName='ButtonExample'
+        componentUrl='https://github.com/OfficeDev/office-ui-fabric-react/tree/master/packages/office-ui-fabric-react/src/components/Button'
         exampleCards={
           <div>
             <Checkbox
@@ -135,43 +136,22 @@ export class ButtonPage extends React.Component<IComponentDemoPageProps, IButton
           />
         }
         overview={
-          <div>
-            <p>Buttons are best used to enable a user to commit a change or complete steps in a task. They are typically found inside forms, dialogs, panels or pages. An example of their usage is confirming the deletion of a file in a confirmation dialog.</p>
-            <p>When considering their place in a layout, contemplate the order in which a user will flow through the UI. As an example, in a form, the individual will need to read and interact with the form fields before submiting the form. Therefore, as a general rule, the button should be placed at the bottom of the UI container (a dialog, panel, or page) which holds the related UI elements.</p>
-            <p>While buttons can technically be used to navigate a user to another part of the experience, this is not recommended unless that navigation is part of an action or their flow.</p>
-            <p>Note that both iconProps and menuIconProps take <Link href='#/components/icon'>IIconProps</Link> to specify name and type.</p>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md') }
+          </PageMarkdown>
         }
         bestPractices={
           <div />
         }
         dos={
-          <div>
-            <ul>
-              <li>Make sure the label conveys a clear purpose of the button to the user.</li>
-              <li>Button labels must describe the action the button will perform and should include a verb. Use concise, specific, self-explanatory labels, usually a single word.</li>
-              <li>Buttons should always include a noun if there is any room for interpretation about what the verb operates on.</li>
-              <li>Consider the affect localization will have on the button and what will happen to components around it.</li>
-              <li>If the button’s label content is dynamic, consider how the button will resize and what will happen to components around it.</li>
-              <li>Use only a single line of text in the label of the button.</li>
-              <li>Expose only one or two buttons to the user at a time, for example, "Accept" and "Cancel". If you need to expose more actions to the user, consider using checkboxes or radio buttons from which the user can select actions, with a single command button to trigger those actions.</li>
-              <li>Show only one primary button that inherits theme color at rest state. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds.</li>
-              <li>"Submit", "OK", and "Apply" buttons should always be styled as primary buttons. When "Reset" or "Cancel" buttons appear alongside one of the above, they should be styled as secondary buttons.</li>
-              <li>Default buttons should always perform safe operations. For example, a default button should never delete.</li>
-              <li>Use task buttons to cause actions that complete a task or cause a transitional task. Do not use buttons to toggle other UX in the same context. For example, a button may be used to open an interface area but should not be used to open an additional set of components in the same interface.</li>
-            </ul>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonDos.md') }
+          </PageMarkdown>
         }
         donts={
-          <div>
-            <ul>
-              <li>Don't use generic labels like "Ok," especially in the case of an error; errors are never "Ok."</li>
-              <li>Don’t place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (i.e. "Save") or cancels the action (i.e. "Cancel").</li>
-              <li>Don’t use a button to navigate to another place, use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used.</li>
-              <li>Don’t put too much text in a button - try to keep the length of your text to a minimum.</li>
-              <li>Don't put anything other than text in a button.</li>
-            </ul>
-          </div>
+          <PageMarkdown>
+            { require<string>('!raw-loader!office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md') }
+          </PageMarkdown>
         }
         isHeaderVisible={ this.props.isHeaderVisible }
         componentStatus={

packages/office-ui-fabric-react/src/components/Button/docs/ButtonDonts.md

@@ -0,0 +1,5 @@
+- Don't use generic labels like "Ok," especially in the case of an error; errors are never "Ok."
+- Don’t place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (i.e. "Save") or cancels the action (i.e. "Cancel").
+- Don’t use a button to navigate to another place, use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used.
+- Don’t put too much text in a button - try to keep the length of your text to a minimum.
+- Don't put anything other than text in a button.

packages/office-ui-fabric-react/src/components/Button/docs/ButtonDos.md

@@ -0,0 +1,11 @@
+- Make sure the label conveys a clear purpose of the button to the user.
+- Button labels must describe the action the button will perform and should include a verb. Use concise, specific, self-explanatory labels, usually a single word.
+- Buttons should always include a noun if there is any room for interpretation about what the verb operates on.
+- Consider the affect localization will have on the button and what will happen to components around it.
+- If the button’s label content is dynamic, consider how the button will resize and what will happen to components around it.
+- Use only a single line of text in the label of the button.
+- Expose only one or two buttons to the user at a time, for example, "Accept" and "Cancel". If you need to expose more actions to the user, consider using checkboxes or radio buttons from which the user can select actions, with a single command button to trigger those actions.
+- Show only one primary button that inherits theme color at rest state. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds.
+- "Submit", "OK", and "Apply" buttons should always be styled as primary buttons. When "Reset" or "Cancel" buttons appear alongside one of the above, they should be styled as secondary buttons.
+- Default buttons should always perform safe operations. For example, a default button should never delete.
+- Use task buttons to cause actions that complete a task or cause a transitional task. Do not use buttons to toggle other UX in the same context. For example, a button may be used to open an interface area but should not be used to open an additional set of components in the same interface.

packages/office-ui-fabric-react/src/components/Button/docs/ButtonOverview.md

@@ -0,0 +1,7 @@
+Buttons are best used to enable a user to commit a change or complete steps in a task. They are typically found inside forms, dialogs, panels or pages. An example of their usage is confirming the deletion of a file in a confirmation dialog.
+
+When considering their place in a layout, contemplate the order in which a user will flow through the UI. As an example, in a form, the individual will need to read and interact with the form fields before submiting the form. Therefore, as a general rule, the button should be placed at the bottom of the UI container (a dialog, panel, or page) which holds the related UI elements.
+
+While buttons can technically be used to navigate a user to another part of the experience, this is not recommended unless that navigation is part of an action or their flow.
+
+Note that both iconProps and menuIconProps take <a href='#/components/icon'>IIconProps</a> to specify name and type.

packages/office-ui-fabric-react/src/components/Button/examples/Button.Icon.Example.tsx

@@ -23,6 +23,7 @@ export class ButtonIconExample extends React.Component<IButtonProps> {
           title='Emoji'
           ariaLabel='Emoji'
         />
+        <p>For a list of Icons, visit our <a href='https://developer.microsoft.com/en-us/fabric#/styles/icons'>Icon documentation</a>.</p>
       </div>
     );
   }