[docs] Do SEO for the components

BACKERS.md

@@ -1,5 +1,7 @@
 # Sponsors & Backers
 
+<p class="description">Support Material-UI’s development.</p>
+
 Material-UI is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to the support of these awesome backers. If you'd like to join them, please consider:
 - [Become a backer or sponsor on Patreon](https://www.patreon.com/oliviertassinari).
 - [Become a backer or sponsor on OpenCollective](https://opencollective.com/material-ui).

CHANGELOG.md

@@ -1448,7 +1448,7 @@ We have documented our approach to solving the problem in #10023. Basically, we
 This is what motivated the button breaking change. Unfortunately `type` has its own meaning in the HTML specification. You can use it on the following elements: `<button>, <input>, <command>, <embed>, <object>, <script>, <source>, <style>, <menu>`.
 We are using a more generic name to **avoid the confusion**: `variant`.
 
-Umbrella pull-request for: #10084, #10086, #10088.
+Umbrella pull request for: #10084, #10086, #10088.
 
 ```diff
 <Button
@@ -2185,7 +2185,7 @@ Big thanks to the 16 contributors who made this release possible.
 
 Here are some highlights ✨:
 - We have removed Flow from the core components in (#9453).
-You can learn more about the motivations in the pull-request.
+You can learn more about the motivations in the pull request.
 This changes two important things:
   - We have reduced the size of the bundle by ~8 kB gzipped.
   - The propTypes runtime checks are back. You might experience new warnings.
@@ -2384,7 +2384,7 @@ Here are some highlights ✨:
 ### Breaking change
 
 - [Select] Remove InputClasses (#9159) @oliviertassinari
-It's a revert. I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull-request #8942. It was not taking the input classes property into account. It was a breaking change and not needed.
+It's a revert. I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull request #8942. It was not taking the input classes property into account. It was a breaking change and not needed.
 - [core] Reduce bundle size by 2kB gzipped (#9129) @oliviertassinari
 We have removed some jss plugins from the default bundle:
   - [jss-expand](https://github.com/cssinjs/jss-expand) (1.3 kB)
@@ -2393,7 +2393,7 @@ We have removed some jss plugins from the default bundle:
   - [jss-template](https://github.com/cssinjs/jss-template) (330 B)
 
 It's a revert.
-I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull-request #8942.
+I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull request #8942.
 It was not taking the input classes property into account.
 It was a breaking change and not needed.
 

GOVERNANCE.md

@@ -1,5 +1,7 @@
 # Mui-Org Governance
 
+<p class="description">Material-UI is an open source project that depends on contributions from the community.</p>
+
 ## Overview
 
 Mui-Org houses projects related to [Material-UI](http://www.material-ui.com/), a set of [React](https://reactjs.org/) components

ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-The roadmap is a living document, and it is likely that priorities will change, but the list below should give some indication of our plans for the next major release, and for the future.
+<p class="description">The roadmap is a living document, and it is likely that priorities will change, but the list below should give some indication of our plans for the next major release, and for the future.</p>
 
 Our priorities:
 1. **Material Design**. The Google Design team has recently released a new iteration on the Material Design specification which is focused on *themability*. This is great news! We will do our best to keep up to date. It also validates that heavily investing in customizability for v1 was a good call. We will continue our efforts in this area.

docs/src/modules/components/AppFrame.js

@@ -38,9 +38,6 @@ Router.onRouteChangeError = () => {
 const styles = theme => ({
   root: {
     display: 'flex',
-    alignItems: 'stretch',
-    minHeight: '100vh',
-    width: '100%',
   },
   grow: {
     flex: '1 1 auto',

docs/src/modules/components/Head.js

@@ -0,0 +1,38 @@
+import React from 'react';
+import NextHead from 'next/head';
+import PropTypes from 'prop-types';
+
+function Head(props) {
+  const { title, description } = props;
+
+  return (
+    <NextHead>
+      <title>{title}</title>
+      <meta name="description" content={description} />
+      {/* Twitter */}
+      <meta name="twitter:card" content="summary_large_image" />
+      <meta name="twitter:site" content="@MaterialUI" />
+      <meta name="twitter:title" content={title} />
+      <meta name="twitter:description" content={description} />
+      <meta name="twitter:image" content="https://material-ui.com/static/brand.png" />
+      {/* Facebook */}
+      <meta property="og:type" content="website" />
+      <meta property="og:title" content={title} />
+      <meta property="og:description" content={description} />
+      <meta property="og:image" content="https://material-ui.com/static/brand.png" />
+      <meta property="og:locale" content="en_US" />
+    </NextHead>
+  );
+}
+
+Head.propTypes = {
+  description: PropTypes.string,
+  title: PropTypes.string,
+};
+
+Head.defaultProps = {
+  description: "React Components that Implement Google's Material Design.",
+  title: "The world's most popular React UI framework - Material-UI",
+};
+
+export default Head;

docs/src/modules/components/MarkdownDocs.js

@@ -2,14 +2,19 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import kebabCase from 'lodash/kebabCase';
 import warning from 'warning';
-import Head from 'next/head';
 import { withStyles } from '@material-ui/core/styles';
 import Button from '@material-ui/core/Button';
 import MarkdownElement from '@material-ui/docs/MarkdownElement';
+import Head from 'docs/src/modules/components/Head';
 import AppContent from 'docs/src/modules/components/AppContent';
 import Demo from 'docs/src/modules/components/Demo';
 import Carbon from 'docs/src/modules/components/Carbon';
-import { getHeaders, getContents, getTitle } from 'docs/src/modules/utils/parseMarkdown';
+import {
+  getHeaders,
+  getContents,
+  getTitle,
+  getDescription,
+} from 'docs/src/modules/utils/parseMarkdown';
 
 const styles = theme => ({
   root: {
@@ -53,9 +58,10 @@ function MarkdownDocs(props, context) {
 
   return (
     <AppContent className={classes.root}>
-      <Head>
-        <title>{`${getTitle(markdown)} - Material-UI`}</title>
-      </Head>
+      <Head
+        title={`${headers.title || getTitle(markdown)} - Material-UI`}
+        description={getDescription(markdown)}
+      />
       <div className={classes.header}>
         <Button component="a" href={`${SOURCE_CODE_ROOT_URL}${markdownLocation}`}>
           {'Edit this page'}

docs/src/modules/utils/generateMarkdown.js

@@ -13,7 +13,12 @@ function normalizePath(path) {
 }
 
 function generateHeader(reactAPI) {
-  return ['---', `filename: ${normalizePath(reactAPI.filename)}`, '---'].join('\n');
+  return [
+    '---',
+    `filename: ${normalizePath(reactAPI.filename)}`,
+    `title: API of ${reactAPI.name}`,
+    '---',
+  ].join('\n');
 }
 
 function getDeprecatedInfo(type) {
@@ -312,6 +317,8 @@ export default function generateMarkdown(reactAPI) {
     '',
     `# ${reactAPI.name}`,
     '',
+    `<p class="description">The API documentation of the ${reactAPI.name} React component.</p>`,
+    '',
     reactAPI.description,
     '',
     generateProps(reactAPI),

docs/src/modules/utils/parseMarkdown.js

@@ -1,5 +1,6 @@
 const headerRegExp = /---[\r\n]([\s\S]*)[\r\n]---/;
 const titleRegExp = /# (.*)[\r\n]/;
+const descriptionRegExp = /<p class="description">(.*)<\/p>[\r\n]/;
 const headerKeyValueRegExp = /(.*): (.*)/g;
 const emptyRegExp = /^\s*$/;
 
@@ -41,5 +42,19 @@ export function getContents(markdown) {
 export function getTitle(markdown) {
   const matches = markdown.match(titleRegExp);
 
-  return matches ? matches[1] : 'Material-UI';
+  if (!matches || !matches[1]) {
+    throw new Error('Missing title in the page');
+  }
+
+  return matches[1];
+}
+
+export function getDescription(markdown) {
+  const matches = markdown.match(descriptionRegExp);
+
+  if (!matches || !matches[1]) {
+    throw new Error('Missing description in the page');
+  }
+
+  return matches[1];
 }

docs/src/pages/customization/css-in-js/css-in-js.md

@@ -1,7 +1,9 @@
 # CSS in JS
 
+<p class="description">You can leverage our styling solution, even if you are not using our components.</p>
+
 Material-UI aims to provide strong foundations for building dynamic UIs.
-For the sake of simplicity, **we expose the internal styling solution to users**.
+For the sake of simplicity, **we expose our styling solution to users**.
 You can use it, but you don't have to. This styling solution is [interoperable with](/guides/interoperability) all the other major solutions.
 
 ## Material-UI's styling solution

docs/src/pages/customization/default-theme/default-theme.md

@@ -1,6 +1,6 @@
 # Default Theme
 
-Here's what the theme object looks like with the default values:
+<p class="description">Here's what the theme object looks like with the default values.</p>
 
 {{"demo": "pages/customization/default-theme/DefaultTheme.js", "hideEditButton": true}}
 

docs/src/pages/customization/overrides/overrides.md

@@ -1,6 +1,6 @@
 # Overrides
 
-As components can be used in different contexts, Material-UI supports four different types of customization requirements going from **the most specific** to **the most generic**:
+<p class="description">As components can be used in different contexts, Material-UI supports different types of customization requirements going from the most specific to the most generic.</p>
 
 1. [Specific variation for a one-time situation](#1-specific-variation-for-a-one-time-situation)
 1. [Dynamic variation for a one-time situation](#2-dynamic-variation-for-a-one-time-situation)

docs/src/pages/customization/themes/themes.md

@@ -1,5 +1,7 @@
 # Themes
 
+<p class="description">Customize Material-UI with our theme.</p>
+
 The theme specifies the color of the components, darkness of the surfaces, level of shadow, appropriate opacity of ink elements, etc.
 
 Themes let you apply a consistent tone to your app. It allows you to **customize all design aspects** of your project in order to meet the specific needs of your business or brand.

docs/src/pages/demos/app-bar/app-bar.md

@@ -1,19 +1,24 @@
 ---
+title: App Bar React component
 components: AppBar, Toolbar
 ---
 
 # App Bar
 
-The [App bar](https://material.io/design/components/app-bars-top.html), formerly known as the action bar in Android, is a special kind of toolbar that’s used for branding, navigation, search, and actions.
+<p class="description">The App Bar displays information and actions relating to the current screen.</p>
 
-## Simple App bar
+The [top App Bar](https://material.io/design/components/app-bars-top.html) provides content and actions related to the current screen. It’s used for branding, screen titles, navigation, and actions.
+
+It can transform into a contextual action bar.
+
+## Simple App Bar
 
 {{"demo": "pages/demos/app-bar/SimpleAppBar.js"}}
 
-## App bar with buttons
+## App Bar with buttons
 
 {{"demo": "pages/demos/app-bar/ButtonAppBar.js"}}
 
-## App bar with menu
+## App Bar with menu
 
 {{"demo": "pages/demos/app-bar/MenuAppBar.js"}}

docs/src/pages/demos/autocomplete/autocomplete.md

@@ -1,10 +1,12 @@
 ---
+title: Autocomplete React component
 components: TextField, Paper, MenuItem
 ---
 
 # Autocomplete
 
-The autocomplete is a normal text input enhanced by a panel of suggested options.
+<p class="description">The autocomplete is a normal text input enhanced by a panel of suggested options.</p>
+
 Material-UI doesn't provide any high-level API for solving this problem.
 We encourage people relying on the solutions the React community has built.
 

docs/src/pages/demos/avatars/avatars.md

@@ -1,10 +1,11 @@
 ---
+title: Avatar React component
 components: Avatar
 ---
 
 # Avatars
 
-Avatars are found throughout material design with uses in everything from tables to dialog menus.
+<p class="description">Avatars are found throughout material design with uses in everything from tables to dialog menus.</p>
 
 ## Image avatars
 

docs/src/pages/demos/badges/badges.md

@@ -1,10 +1,11 @@
 ---
+title: Badge React component
 components: Badge
 ---
 
 # Badge
 
-Badge generates a small badge to the top-right of its child(ren).
+<p class="description">Badge generates a small badge to the top-right of its child(ren).</p>
 
 ## Simple Badges
 

docs/src/pages/demos/bottom-navigation/bottom-navigation.md

@@ -1,12 +1,16 @@
 ---
+title: Bottom Navigation React component
 components: BottomNavigation, BottomNavigationAction
 ---
 
 # Bottom Navigation
 
-[Bottom navigation](https://material.io/design/components/bottom-navigation.html) bars make it easy to explore and switch between top-level views in a single tap.
+<p class="description">Bottom navigation bars allow movement between primary destinations in an app.</p>
+
+[Bottom navigation](https://material.io/design/components/bottom-navigation.html) bars display three to five destinations at the bottom of a screen. Each destination is represented by an icon and an optional text label. When a bottom navigation icon is tapped, the user is taken to the top-level navigation destination associated with that icon.
 
 ## Bottom Navigation
+
 When there are only **three** actions, display both icons and text labels at all times.
 
 {{"demo": "pages/demos/bottom-navigation/SimpleBottomNavigation.js"}}

docs/src/pages/demos/buttons/buttons.md

@@ -1,14 +1,18 @@
 ---
+title: Button React component
 components: Button, IconButton, ButtonBase, Zoom
 ---
 
 # Buttons
 
-[Buttons](https://material.io/design/components/buttons.html) communicate the action that will occur when the user touches them.
+<p class="description">Buttons allow users to take actions, and make choices, with a single tap.</p>
 
-Material buttons trigger an ink reaction on press.
-They may display text, imagery, or both.
-Text buttons and Contained buttons are the most commonly used types.
+[Buttons](https://material.io/design/components/buttons.html) communicate actions that users can take. They are typically placed throughout your UI, in places like:
+- Dialogs
+- Modal windows
+- Forms
+- Cards
+- Toolbars
 
 ## Text Buttons
 
@@ -45,7 +49,7 @@ They contain actions that are primary to your app.
 
 A [floating action button](https://material.io/design/components/buttons-floating-action-button.html)
 (FAB) performs the primary, or most common, action on a screen.
-It appears in front of all screen content, typically as a circular shape with an icon in its center. 
+It appears in front of all screen content, typically as a circular shape with an icon in its center.
 FABs come in three types: regular, mini, and extended.
 
 Only use a FAB if it is the most suitable way to present a screen’s primary action.

docs/src/pages/demos/cards/cards.md

@@ -1,14 +1,15 @@
 ---
+title: Cards React component
 components: Card, CardActions, CardContent, CardHeader, CardMedia, Collapse
 ---
 
 # Cards
 
-A [card](https://material.io/design/components/cards.html) is a sheet of material that serves as an entry point to more detailed information.
+<p class="description">Cards contain content and actions about a single subject.</p>
 
-Cards display content composed of different elements whose size or supported actions vary.
+[Cards](https://material.io/design/components/cards.html) are surfaces that display content and actions on a single topic.
 
-Cards are a convenient means of displaying content composed of different elements. They’re also well-suited for showcasing elements whose size or supported actions vary, like photos with captions of variable length.
+They should be easy to scan for relevant and actionable information. Elements, like text and images, should be placed on them in a way that clearly indicates hierarchy.
 
 ## Simple Card
 

docs/src/pages/demos/chips/chips.md

@@ -1,11 +1,13 @@
 ---
+title: Chip React component
 components: Chip
 ---
 
 # Chips
 
-[Chips](https://material.io/design/components/chips.html)
-represent complex entities in small blocks, such as a contact.
+<p class="description">Chips are compact elements that represent an input, attribute, or action.</p>
+
+[Chips](https://material.io/design/components/chips.html) allow users to enter information, make selections, filter content, or trigger actions.
 
 While included here as a standalone component, the most common use will
 be in some form of input, so some of the behaviour demonstrated here is