From 68c2f160ca0d287397bd0fe901aeac626a333180 Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Sun, 24 Jun 2018 17:20:29 +0200
Subject: [PATCH] [docs] Do SEO for the components

---
 BACKERS.md                                    |  2 +
 CHANGELOG.md                                  |  8 ++--
 GOVERNANCE.md                                 |  2 +
 ROADMAP.md                                    |  2 +-
 docs/src/modules/components/AppFrame.js       |  3 --
 docs/src/modules/components/Head.js           | 38 +++++++++++++++++++
 docs/src/modules/components/MarkdownDocs.js   | 13 ++++---
 docs/src/modules/utils/parseMarkdown.js       | 17 ++++++++-
 .../discover-more/changelog/changelog.md      |  2 +
 .../discover-more/community/community.md      |  2 +-
 .../related-projects/related-projects.md      |  5 ++-
 .../pages/discover-more/showcase/showcase.md  |  2 +-
 docs/src/pages/discover-more/team/team.md     |  2 +-
 docs/src/pages/discover-more/vision/vision.md |  2 +-
 .../getting-started/comparison/comparison.md  |  4 +-
 .../example-projects/example-projects.md      |  2 +-
 docs/src/pages/getting-started/faq/faq.md     |  2 +-
 .../installation/installation.md              |  2 +
 .../supported-components.md                   |  5 +--
 .../supported-platforms.md                    |  2 +
 docs/src/pages/getting-started/usage/Usage.js |  2 -
 docs/src/pages/getting-started/usage/usage.md |  2 +
 docs/src/pages/guides/api/api.md              | 13 +++----
 .../pages/guides/composition/composition.md   |  2 +-
 docs/src/pages/guides/csp/csp.md              |  2 +-
 docs/src/pages/guides/flow/flow.md            |  3 +-
 .../interoperability/interoperability.md      |  7 ++--
 .../guides/migration-v0x/migration-v0x.md     |  4 +-
 .../minimizing-bundle-size.md                 |  2 +
 .../guides/right-to-left/right-to-left.md     |  2 +-
 .../server-rendering/server-rendering.md      |  3 +-
 docs/src/pages/guides/testing/testing.md      |  3 ++
 .../src/pages/guides/typescript/typescript.md |  3 +-
 docs/src/pages/lab/about/about.md             |  7 ++--
 .../pages/premium-themes/premium-themes.md    |  2 +-
 docs/src/pages/style/color/color.md           |  4 ++
 .../pages/style/css-baseline/css-baseline.md  |  3 +-
 docs/src/pages/style/icons/icons.md           |  4 +-
 docs/src/pages/style/typography/typography.md |  2 +-
 docs/src/pages/versions/StableVersions.js     |  5 ++-
 docs/src/pages/versions/versions.md           |  7 ++++
 package.json                                  |  2 +-
 .../src/MarkdownElement/MarkdownElement.js    | 12 ++++--
 pages/_document.js                            | 26 +------------
 pages/index.js                                |  6 +--
 yarn.lock                                     |  2 +-
 46 files changed, 158 insertions(+), 89 deletions(-)
 create mode 100644 docs/src/modules/components/Head.js

diff --git a/BACKERS.md b/BACKERS.md
index 4b820ee0bbb49f..85bed5ebb32bf4 100644
--- a/BACKERS.md
+++ b/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).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5291570fa11269..4ff532a23ba98f 100644
--- a/CHANGELOG.md
+++ b/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.
 
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index 4cf4b73bd4e3d0..49b304f489b94e 100644
--- a/GOVERNANCE.md
+++ b/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
diff --git a/ROADMAP.md b/ROADMAP.md
index f87a7bca6e439a..0666ad396fef82 100644
--- a/ROADMAP.md
+++ b/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.
diff --git a/docs/src/modules/components/AppFrame.js b/docs/src/modules/components/AppFrame.js
index 3ce23d584a270a..7857d5da2a45ec 100644
--- a/docs/src/modules/components/AppFrame.js
+++ b/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',
diff --git a/docs/src/modules/components/Head.js b/docs/src/modules/components/Head.js
new file mode 100644
index 00000000000000..3b938cc2cc6786
--- /dev/null
+++ b/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: 'Material-UI',
+};
+
+export default Head;
diff --git a/docs/src/modules/components/MarkdownDocs.js b/docs/src/modules/components/MarkdownDocs.js
index 9456580f3abfaa..4f74f934001bf1 100644
--- a/docs/src/modules/components/MarkdownDocs.js
+++ b/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,7 @@ function MarkdownDocs(props, context) {
 
   return (
     <AppContent className={classes.root}>
-      <Head>
-        <title>{`${getTitle(markdown)} - Material-UI`}</title>
-      </Head>
+      <Head title={`${getTitle(markdown)} - Material-UI`} description={getDescription(markdown)} />
       <div className={classes.header}>
         <Button component="a" href={`${SOURCE_CODE_ROOT_URL}${markdownLocation}`}>
           {'Edit this page'}
diff --git a/docs/src/modules/utils/parseMarkdown.js b/docs/src/modules/utils/parseMarkdown.js
index e1f141e0b6e2d7..0ad71188c92b4c 100644
--- a/docs/src/modules/utils/parseMarkdown.js
+++ b/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]) {
+    return null;
+  }
+
+  return matches[1];
 }
diff --git a/docs/src/pages/discover-more/changelog/changelog.md b/docs/src/pages/discover-more/changelog/changelog.md
index cd0cd3bf8395ce..731acf5d3dd060 100644
--- a/docs/src/pages/discover-more/changelog/changelog.md
+++ b/docs/src/pages/discover-more/changelog/changelog.md
@@ -1,3 +1,5 @@
 # Changelog
 
+<p class="description">Material-UI strictly follows Semantic Versioning 2.0.0.</p>
+
 All notable changes are described in the [CHANGELOG.md file](https://github.com/mui-org/material-ui/blob/master/CHANGELOG.md).
diff --git a/docs/src/pages/discover-more/community/community.md b/docs/src/pages/discover-more/community/community.md
index 53d38c9316bf7a..3de28962ef0716 100644
--- a/docs/src/pages/discover-more/community/community.md
+++ b/docs/src/pages/discover-more/community/community.md
@@ -1,6 +1,6 @@
 # Community
 
-If you want to stay up to date on the development of Material-UI or to reach out to the community, you can follow those resources:
+<p class="description">If you want to stay up to date on the development of Material-UI or to reach out to the community, you can follow those resources.</p>
 
 - Chat with us on [Gitter](https://gitter.im/mui-org/material-ui).
 - For help using Material-UI, ask on StackOverflow using the tag
diff --git a/docs/src/pages/discover-more/related-projects/related-projects.md b/docs/src/pages/discover-more/related-projects/related-projects.md
index 29787bd2ed9456..ecf9403f2b6db8 100644
--- a/docs/src/pages/discover-more/related-projects/related-projects.md
+++ b/docs/src/pages/discover-more/related-projects/related-projects.md
@@ -1,9 +1,10 @@
 # Related projects
 
+<p class="description">We have built a carefully curated collection of libraries that worth giving a look.</p>
+
 Because the scope of problems Material-UI solves is limited, we try to play nicely with
 other libraries.
-We have built a carefully curated collection of libraries that worth giving a look.
-Feel free to submit a pull-request to add more projects; we will accept them if they match our criteria.
+Feel free to submit a pull request to add more projects; we will accept them if they match our criteria.
 
 ## Material-UI Specific Projects
 
diff --git a/docs/src/pages/discover-more/showcase/showcase.md b/docs/src/pages/discover-more/showcase/showcase.md
index 0be89854d79e64..f4f13043a90006 100644
--- a/docs/src/pages/discover-more/showcase/showcase.md
+++ b/docs/src/pages/discover-more/showcase/showcase.md
@@ -1,6 +1,6 @@
 # Showcase
 
-The following is a list of some of the public apps using Material-UI. Not all of them have their interface implemented using 100% Material-UI.
+<p class="description">The following is a list of some of the public apps using Material-UI.</p>
 
 Want to add your app? Found an app that no longer works or no longer uses Material-UI? Please submit a pull request on [GitHub](https://github.com/mui-org/material-ui) to update this page!
 
diff --git a/docs/src/pages/discover-more/team/team.md b/docs/src/pages/discover-more/team/team.md
index 15fba5a8c0ebf6..10fe2b0aaf0f32 100644
--- a/docs/src/pages/discover-more/team/team.md
+++ b/docs/src/pages/discover-more/team/team.md
@@ -1,6 +1,6 @@
 # Team
 
-An overview of the founding team and core contributors to Material-UI.
+<p class="description">An overview of the founding team and core contributors to Material-UI.</p>
 
 Material-UI is maintained by a small group of invaluable core contributors, with the massive support and involvement of our community.
 The development of the project and its ecosystem is guided by an international team, some of whom have chosen to be featured below.
diff --git a/docs/src/pages/discover-more/vision/vision.md b/docs/src/pages/discover-more/vision/vision.md
index 3f96130579ed8d..96ee7dd7c9943a 100644
--- a/docs/src/pages/discover-more/vision/vision.md
+++ b/docs/src/pages/discover-more/vision/vision.md
@@ -1,6 +1,6 @@
 # Material-UI’s Vision
 
-Our vision is to provide an elegant React implementation of the [Material Design guidelines](https://material.io/design/) **that can be customized to fully match your brand**.
+<p class="description">Our vision is to provide an elegant React implementation of the Material Design guidelines that can be customized to fully match your brand.</p>
 
 The Material Design guidelines are an incredible starting point, but they do not provide guidance on all aspects or needs of an application. In addition to the guidelines-specific implementation, we want Material-UI to become whatever is generally useful for application development, all in the spirit of the Material Design guidelines.
 
diff --git a/docs/src/pages/getting-started/comparison/comparison.md b/docs/src/pages/getting-started/comparison/comparison.md
index fefd1d4bc4e230..666f138460af96 100644
--- a/docs/src/pages/getting-started/comparison/comparison.md
+++ b/docs/src/pages/getting-started/comparison/comparison.md
@@ -1,9 +1,9 @@
 # Comparison with other libraries
 
+<p class="description">You’re here because you want to know if Material-UI can solve your specific problems better. That’s what we hope to answer for you here.</p>
+
 This is definitely one of the most challenging pages in the guide to write, but we do feel it’s important.
 Odds are, you’ve had problems you tried to solve and you’ve used another library to solve them.
-You’re here because you want to know if Material-UI can solve your specific problems better.
-That’s what we hope to answer for you here.
 
 We’d like your help keeping this document up-to-date because the JavaScript world moves fast!
 If you notice an inaccuracy or something that doesn’t seem quite right, please let us know by
diff --git a/docs/src/pages/getting-started/example-projects/example-projects.md b/docs/src/pages/getting-started/example-projects/example-projects.md
index e311f336e0e2c6..f64a04578a173c 100644
--- a/docs/src/pages/getting-started/example-projects/example-projects.md
+++ b/docs/src/pages/getting-started/example-projects/example-projects.md
@@ -1,6 +1,6 @@
 # Example Projects
 
-Are you looking for an example project to get started?
+<p class="description">Are you looking for an example project to get started?</p>
 
 We host some example projects which you can find in the [GitHub repository](https://github.com/mui-org/material-ui) under the [`/examples`](https://github.com/mui-org/material-ui/tree/master/examples) folder:
 - [Create React App](https://github.com/mui-org/material-ui/tree/master/examples/create-react-app)
diff --git a/docs/src/pages/getting-started/faq/faq.md b/docs/src/pages/getting-started/faq/faq.md
index 14c5325b773e55..9b94c69906cad5 100644
--- a/docs/src/pages/getting-started/faq/faq.md
+++ b/docs/src/pages/getting-started/faq/faq.md
@@ -1,6 +1,6 @@
 # Frequently Asked Questions
 
-Stuck on a particular problem? Check some of these common gotchas first.
+<p class="description">Stuck on a particular problem? Check some of these common gotchas first.</p>
 
 If you still can't find what you're looking for, you can ask the community in [gitter](https://gitter.im/mui-org/material-ui).
 For how-to questions and other non-issues, please use [StackOverflow](https://stackoverflow.com/questions/tagged/material-ui) instead of Github issues. There is a StackOverflow tag called `material-ui` that you can use to tag your questions.
diff --git a/docs/src/pages/getting-started/installation/installation.md b/docs/src/pages/getting-started/installation/installation.md
index 0d8b89cc6cd786..c0bfe5774d9f33 100644
--- a/docs/src/pages/getting-started/installation/installation.md
+++ b/docs/src/pages/getting-started/installation/installation.md
@@ -1,5 +1,7 @@
 # Installation
 
+<p class="description">Install Material-UI, the world’s most popular React UI framework.</p>
+
 Material-UI is available as an [npm package](https://www.npmjs.com/package/@material-ui/core).
 
 ## npm
diff --git a/docs/src/pages/getting-started/supported-components/supported-components.md b/docs/src/pages/getting-started/supported-components/supported-components.md
index dbdb3f79028c3e..45e9a10349fa00 100644
--- a/docs/src/pages/getting-started/supported-components/supported-components.md
+++ b/docs/src/pages/getting-started/supported-components/supported-components.md
@@ -1,7 +1,6 @@
 # Supported Components
 
-The following is a list of Material Design components & features.
-Those currently supported by Material-UI are **highlighted ✓**.
+<p class="description">The following is a list of Material Design components & features. Those currently supported by Material-UI are highlighted ✓.</p>
 
 While we strive to follow the guidelines where practical (applying
 common sense where guidelines contradict - a more common occurrence than
@@ -11,7 +10,7 @@ allow developers to create compelling user interfaces and experiences.
 
 If you wish to add support for a component or feature not highlighted
 here, please search for the relevant [GitHub Issue](https://github.com/mui-org/material-ui/issues), or create a new one
-to discuss the approach before submitting a PR.
+to discuss the approach before submitting a pull request.
 
 - App bars
   - **[Top](https://material.io/design/components/app-bars-top.html) ✓**
diff --git a/docs/src/pages/getting-started/supported-platforms/supported-platforms.md b/docs/src/pages/getting-started/supported-platforms/supported-platforms.md
index 3351a728f0be75..a26d844b2e0c72 100644
--- a/docs/src/pages/getting-started/supported-platforms/supported-platforms.md
+++ b/docs/src/pages/getting-started/supported-platforms/supported-platforms.md
@@ -1,5 +1,7 @@
 # Supported Platforms
 
+<p class="description">Learn about the platforms, from modern to old, that are supported by Material-UI.</p>
+
 ## Browser
 
 Material-UI supports the latest, stable releases of all major browsers and platforms.
diff --git a/docs/src/pages/getting-started/usage/Usage.js b/docs/src/pages/getting-started/usage/Usage.js
index 725458b987c950..5e7168a85dcec7 100644
--- a/docs/src/pages/getting-started/usage/Usage.js
+++ b/docs/src/pages/getting-started/usage/Usage.js
@@ -9,8 +9,6 @@ function Usage() {
         width: '100%',
         height: 350,
         border: 0,
-        borderRadius: 4,
-        overflow: 'hidden',
       }}
       sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
     />
diff --git a/docs/src/pages/getting-started/usage/usage.md b/docs/src/pages/getting-started/usage/usage.md
index a5093da2816354..567b824686a1c1 100644
--- a/docs/src/pages/getting-started/usage/usage.md
+++ b/docs/src/pages/getting-started/usage/usage.md
@@ -1,5 +1,7 @@
 # Usage
 
+<p class="description">Get started with React and Material-UI in no time.</p>
+
 Material-UI components work in isolation.
 **They are self-supporting**, and will inject, and only inject, the styles they need to display.
 They don't rely on any global style-sheets such as [normalize.css](https://github.com/necolas/normalize.css/),
diff --git a/docs/src/pages/guides/api/api.md b/docs/src/pages/guides/api/api.md
index 88b54510322c67..85bff55b8ce7cc 100644
--- a/docs/src/pages/guides/api/api.md
+++ b/docs/src/pages/guides/api/api.md
@@ -1,7 +1,6 @@
 # API Design Approach
 
-We have learned a great deal regarding how Material-UI is used,
-and the 1.x.x rewrite allowed us to completely rethink the component API.
+<p class="description">We have learned a great deal regarding how Material-UI is used, and the v1 rewrite allowed us to completely rethink the component API.</p>
 
 > API design is hard because you can make it seem simple but it's actually deceptively complex, or make it actually simple but seem complex.
 
@@ -48,7 +47,7 @@ to make the classes structure as simple as possible, while sufficient to impleme
 - The class applied to the root element is always called `root`.
 - All the default styles are grouped in a single class.
 - The classes applied to non-root elements are prefixed with the name of the element, e.g. `paperWidthXs` in the Dialog component.
-- The variants applied by a boolean property **aren't** prefixed, e.g. the `rounded` class 
+- The variants applied by a boolean property **aren't** prefixed, e.g. the `rounded` class
 applied by the `rounded` property.
 - The variants applied by and enum property **are** prefixed, e.g. the `colorPrimary` class
 applied by the `color="primary"` property.
@@ -113,10 +112,10 @@ For example, let's take a button that has different types. Each option has its p
     fab: boolean;
   };
   ```
-  
+
    This API enabled the shorthand notation:
    `<Button>`, `<Button raised />`, `<Button fab />`.
-   
+
 - Option 2 *enum*:
 
   ```tsx
@@ -124,10 +123,10 @@ For example, let's take a button that has different types. Each option has its p
     variant: 'flat' | 'raised' | 'fab';
   }
   ```
-  
+
   This API is more verbose:
   `<Button>`, `<Button variant="contained">`, `<Button variant="fab">`.
-  
+
    However it prevents an invalid combination from being used,
    bounds the number of properties exposed,
    and can easily support new values in the future.
diff --git a/docs/src/pages/guides/composition/composition.md b/docs/src/pages/guides/composition/composition.md
index 084116bf62ba24..cc6946e5e99ca9 100644
--- a/docs/src/pages/guides/composition/composition.md
+++ b/docs/src/pages/guides/composition/composition.md
@@ -1,6 +1,6 @@
 # Composition
 
-Material-UI tries to make composition as easy as possible.
+<p class="description">Material-UI tries to make composition as easy as possible.</p>
 
 ## Wrapping components
 
diff --git a/docs/src/pages/guides/csp/csp.md b/docs/src/pages/guides/csp/csp.md
index 5eec85319c1f3f..6903fa168dfb37 100644
--- a/docs/src/pages/guides/csp/csp.md
+++ b/docs/src/pages/guides/csp/csp.md
@@ -1,6 +1,6 @@
 # Content Security Policy (CSP)
 
-Starting with JSS version 9.6.0, Material-UI supports Content Security Policy headers.
+<p class="description">Material-UI supports Content Security Policy headers.</p>
 
 ## What is CSP and why is it useful?
 
diff --git a/docs/src/pages/guides/flow/flow.md b/docs/src/pages/guides/flow/flow.md
index ccea1299557e4b..1f1a18952683dd 100644
--- a/docs/src/pages/guides/flow/flow.md
+++ b/docs/src/pages/guides/flow/flow.md
@@ -1,6 +1,7 @@
 # Flow
 
-You can add static typing to JavaScript to improve developer productivity and code quality thanks to [Flow](https://github.com/facebook/flow).
+<p class="description">You can add static typing to JavaScript to improve developer productivity and code quality thanks to Flow.</p>
+
 Have a look at the [Create React App with Flow](https://github.com/mui-org/material-ui/tree/master/examples/create-react-app-with-flow) example.
 
 ## flow-typed
diff --git a/docs/src/pages/guides/interoperability/interoperability.md b/docs/src/pages/guides/interoperability/interoperability.md
index c8fc87d59e51e7..e59275a7084813 100644
--- a/docs/src/pages/guides/interoperability/interoperability.md
+++ b/docs/src/pages/guides/interoperability/interoperability.md
@@ -1,10 +1,9 @@
 # Style Library Interoperability
 
-While it is simple to use the JSS based styling solution provided by Material-UI to style your application,
-it is possible to use any styling solution you prefer, from plain CSS to any number of CSS-in-JS libraries.
+<p class="description">While it is simple to use the JSS based styling solution provided by Material-UI to style your application, it is possible to use any styling solution you prefer, from plain CSS to any number of CSS-in-JS libraries.</p>
 
-This guide aims to document the most popular alternatives, but you should find that the principals
-applied here can be adapted to other libraries.
+This guide aims to document the most popular alternatives,
+but you should find that the principals applied here can be adapted to other libraries.
 
 We have provided examples for the following styling solutions:
 
diff --git a/docs/src/pages/guides/migration-v0x/migration-v0x.md b/docs/src/pages/guides/migration-v0x/migration-v0x.md
index a212e0dcc0a0ba..d92d118fb681be 100644
--- a/docs/src/pages/guides/migration-v0x/migration-v0x.md
+++ b/docs/src/pages/guides/migration-v0x/migration-v0x.md
@@ -1,5 +1,7 @@
 # Migration From v0.x
 
+<p class="description">Yeah, v1 has been released!</p>
+
 ## FAQ
 
 ### Woah - the API is way different! Does that mean 1.0 is completely different, I’ll have to learn the basics all over again, and migrating will be practically impossible?
@@ -10,7 +12,7 @@ We have been making lower-level components, abstracting less complexity.
 
 ### What motivated such a large change?
 
-Material-UI was started [3 years ago](https://github.com/mui-org/material-ui/commit/28b768913b75752ecf9b6bb32766e27c241dbc46).
+Material-UI was started [4 years ago](https://github.com/mui-org/material-ui/commit/28b768913b75752ecf9b6bb32766e27c241dbc46).
 The ecosystem has evolved a lot since then, we have also learned a lot.
 [@nathanmarks](https://github.com/nathanmarks/) started an ambitious task, rebuilding Material-UI from the **ground-up**
 taking advantage of this knowledge to address long-standing issues. To name some of the major changes:
diff --git a/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md b/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
index b6ce39cd943523..ed48baca423005 100644
--- a/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
+++ b/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
@@ -1,5 +1,7 @@
 # Minimizing Bundle Size
 
+<p class="description">Learn more about the tools you can leverage to reduce the bundle size.</p>
+
 ## Bundle size matters
 
 The bundle size of Material-UI is taken very seriously, so
diff --git a/docs/src/pages/guides/right-to-left/right-to-left.md b/docs/src/pages/guides/right-to-left/right-to-left.md
index 0d592f950da992..386c96f7fab32a 100644
--- a/docs/src/pages/guides/right-to-left/right-to-left.md
+++ b/docs/src/pages/guides/right-to-left/right-to-left.md
@@ -1,6 +1,6 @@
 # Right-to-left
 
-To change the direction of Material-UI components you must follow the following steps:
+<p class="description">To change the direction of Material-UI components you must follow the following steps.</p>
 
 ## Steps
 
diff --git a/docs/src/pages/guides/server-rendering/server-rendering.md b/docs/src/pages/guides/server-rendering/server-rendering.md
index 0d0643760949bf..6991d6f3707ae7 100644
--- a/docs/src/pages/guides/server-rendering/server-rendering.md
+++ b/docs/src/pages/guides/server-rendering/server-rendering.md
@@ -1,6 +1,7 @@
 # Server Rendering
 
-The most common use case for server-side rendering is to handle the *initial render* when a user (or search engine crawler) first requests your app.
+<p class="description">The most common use case for server-side rendering is to handle the initial render when a user (or search engine crawler) first requests your app.</p>
+
 When the server receives the request, it renders the required component(s) into an HTML string, and then sends it as a response to the client.
 From that point on, the client takes over rendering duties.
 
diff --git a/docs/src/pages/guides/testing/testing.md b/docs/src/pages/guides/testing/testing.md
index f1f55461be40e4..286376d73c6ff6 100644
--- a/docs/src/pages/guides/testing/testing.md
+++ b/docs/src/pages/guides/testing/testing.md
@@ -1,11 +1,14 @@
 # Testing
 
+<p class="description">Write tests to prevent regressions.</p>
+
 ## Internal
 
 We take tests seriously. We have written and maintain **a wide range** of tests so we can
 iterate with confidence on the components, for instance, the visual regression tests provided by [Argos-CI](https://www.argos-ci.com/mui-org/material-ui) have proven to be really helpful.
 To learn more about our internal tests, you can have a look at the [README](https://github.com/mui-org/material-ui/blob/master/test/README.md).
 
+While we have reached the 100% test coverage achievement, we don't encourage our users to do the same.
 [![Coverage Status](https://img.shields.io/codecov/c/github/mui-org/material-ui/master.svg)](https://codecov.io/gh/mui-org/material-ui/branch/master)
 
 ## Userspace
diff --git a/docs/src/pages/guides/typescript/typescript.md b/docs/src/pages/guides/typescript/typescript.md
index 7ff1bb575887ec..3778e67b02c5a7 100644
--- a/docs/src/pages/guides/typescript/typescript.md
+++ b/docs/src/pages/guides/typescript/typescript.md
@@ -1,6 +1,7 @@
 # TypeScript
 
-You can add static typing to JavaScript to improve developer productivity and code quality thanks to [TypeScript](https://www.typescriptlang.org/).
+<p class="description">You can add static typing to JavaScript to improve developer productivity and code quality thanks to TypeScript.</p>
+
 Have a look at the [Create React App with TypeScript](https://github.com/mui-org/material-ui/tree/master/examples/create-react-app-with-typescript) example. A minimum version of TypeScript 2.8 is required.
 
 ## Usage of `withStyles`
diff --git a/docs/src/pages/lab/about/about.md b/docs/src/pages/lab/about/about.md
index ead22b785d8590..20f46709afc3dd 100644
--- a/docs/src/pages/lab/about/about.md
+++ b/docs/src/pages/lab/about/about.md
@@ -1,6 +1,6 @@
 # About The Lab
 
-This package hosts the incubator components that are not yet ready to move to `core`.
+<p class="description">This package hosts the incubator components that are not yet ready to move to `core`.</p>
 
 ## Installation
 
@@ -13,8 +13,9 @@ npm install @material-ui/lab
 If you are not already using Material-UI in your project, you can add it with:
 
 ```sh
-// npm
+// with npm
 npm install @material-ui/core
-//yarn
+
+// with yarn
 yarn add @material-ui/core
 ```
diff --git a/docs/src/pages/premium-themes/premium-themes.md b/docs/src/pages/premium-themes/premium-themes.md
index dd95240a1e4c30..faab84f8788e4c 100644
--- a/docs/src/pages/premium-themes/premium-themes.md
+++ b/docs/src/pages/premium-themes/premium-themes.md
@@ -1,5 +1,5 @@
 # Premium Themes
 
-Themes built by or reviewed by Material-UI's creators.
+<p class="description">Themes built by or reviewed by Material-UI's creators.</p>
 
 {{"demo": "pages/premium-themes/PremiumThemes.js", "hideHeader": true}}
diff --git a/docs/src/pages/style/color/color.md b/docs/src/pages/style/color/color.md
index f2376c8b5837cf..344858387cc058 100644
--- a/docs/src/pages/style/color/color.md
+++ b/docs/src/pages/style/color/color.md
@@ -1,9 +1,13 @@
 # Color
 
+<p class="description">Convey meaning through color. Out of the box you get access to all colors in the Material Design spec.</p>
+
 [Color](https://material.io/design/color/) in material design is inspired by bold hues juxtaposed with muted environments, deep shadows, and bright highlights.
 
 ## Color system
 
+The Material Design color system can be used to create a color theme that reflects your brand or style.
+
 ### Important Terms
 
 #### "Palette"
diff --git a/docs/src/pages/style/css-baseline/css-baseline.md b/docs/src/pages/style/css-baseline/css-baseline.md
index 3ec595c9d84fb4..7ac8b7d50fcbfb 100644
--- a/docs/src/pages/style/css-baseline/css-baseline.md
+++ b/docs/src/pages/style/css-baseline/css-baseline.md
@@ -4,8 +4,9 @@ components: CssBaseline
 
 # CSS Baseline
 
+<p class="description">Material-UI provides a CssBaseline component to kickstart an elegant, consistent, and simple baseline to build upon.</p>
+
 You might be familiar with [normalize.css](https://github.com/necolas/normalize.css), a collection of HTML element and attribute style-normalizations.
-Material-UI provides a `CssBaseline` component to kickstart an elegant, consistent, and simple baseline to build upon.
 
 ```jsx
 import React from 'react';
diff --git a/docs/src/pages/style/icons/icons.md b/docs/src/pages/style/icons/icons.md
index 3b32534ce36841..4a08e8e110af41 100644
--- a/docs/src/pages/style/icons/icons.md
+++ b/docs/src/pages/style/icons/icons.md
@@ -4,6 +4,8 @@ components: Icon, SvgIcon
 
 # Icons
 
+<p class="description">Guidance and suggestions for using icons with Material-UI.</p>
+
 ## System icons
 
 A [system icon](https://material.io/design/iconography/system-icons.html) or UI icon,
@@ -42,7 +44,7 @@ When importing an icon, keep in mind that the names of the icons are `PascalCase
 - [`alarm`](https://material.io/tools/icons/?icon=alarm&style=baseline) is exposed as `@material-ui/icons/Alarm`
 - [`alarm off`](https://material.io/tools/icons/?icon=alarm_off&style=baseline) is exposed as `@material-ui/icons/AlarmOff`
 
-There is one exception to this rule: 
+There is one exception to this rule:
 - [`3d_rotation`](https://material.io/tools/icons/?icon=3d_rotation&style=baseline) is exposed as `@material-ui/icons/ThreeDRotation`.
 
 {{"demo": "pages/style/icons/SvgMaterialIcons.js"}}
diff --git a/docs/src/pages/style/typography/typography.md b/docs/src/pages/style/typography/typography.md
index 470773e3d71ef8..de36e38e4c8cac 100644
--- a/docs/src/pages/style/typography/typography.md
+++ b/docs/src/pages/style/typography/typography.md
@@ -4,7 +4,7 @@ components: Typography
 
 # Typography
 
-Use typography to present your design and content as clearly and efficiently as possible.
+<p class="description">Use typography to present your design and content as clearly and efficiently as possible.</p>
 
 Too many type sizes and styles at once can spoil any layout.
 A [typographic scale](https://material.io/design/typography/#type-scale) has a limited set of type sizes that work well together along with the layout grid.
diff --git a/docs/src/pages/versions/StableVersions.js b/docs/src/pages/versions/StableVersions.js
index 52108a69138eb5..8f303b7f2dd707 100644
--- a/docs/src/pages/versions/StableVersions.js
+++ b/docs/src/pages/versions/StableVersions.js
@@ -82,7 +82,10 @@ class StableVersions extends React.Component {
               return (
                 <TableRow key={doc.version}>
                   <TableCell padding="dense">
-                    <Typography>{doc.version}</Typography>
+                    <Typography>
+                      {doc.version}
+                      {doc.version === `v${process.env.LIB_VERSION}` ? ' ✓' : ''}
+                    </Typography>
                   </TableCell>
                   <TableCell padding="dense">
                     <Typography
diff --git a/docs/src/pages/versions/versions.md b/docs/src/pages/versions/versions.md
index 0d1341289b33f8..e0c573b5505336 100644
--- a/docs/src/pages/versions/versions.md
+++ b/docs/src/pages/versions/versions.md
@@ -1,5 +1,12 @@
 # Material-UI Versions
 
+<p class="description">You can come back to this page and switch the version of the docs you're reading at any time.</p>
+
+## Release Schedule
+
+- Weekly release: patch or minor version at the end of every week for routine bugfix or new features (anytime for urgent bugfix).
+- Major version release is not included in this schedule for breaking change and new features.
+
 ## Stable versions
 
 The most recent version is recommended in production.
diff --git a/package.json b/package.json
index a52e7599b8e5d1..313d6480cdcd2c 100644
--- a/package.json
+++ b/package.json
@@ -151,7 +151,7 @@
     "rollup-plugin-uglify": "^4.0.0",
     "sinon": "^6.0.0",
     "size-limit": "^0.18.0",
-    "typescript": "^2.6.1",
+    "typescript": "^2.8.0",
     "url-loader": "^1.0.1",
     "vrtest": "^0.2.0",
     "webfontloader": "^1.6.28",
diff --git a/packages/material-ui-docs/src/MarkdownElement/MarkdownElement.js b/packages/material-ui-docs/src/MarkdownElement/MarkdownElement.js
index 25e696c817302f..278b3ebb8df661 100644
--- a/packages/material-ui-docs/src/MarkdownElement/MarkdownElement.js
+++ b/packages/material-ui-docs/src/MarkdownElement/MarkdownElement.js
@@ -110,22 +110,26 @@ const styles = theme => ({
     '& h1': {
       ...theme.typography.display2,
       color: theme.palette.text.secondary,
-      margin: '0.7em 0',
+      margin: `${theme.spacing.unit * 4}px 0 ${theme.spacing.unit * 2}px`,
+    },
+    '& .description': {
+      ...theme.typography.headline,
+      margin: `0 0 ${theme.spacing.unit * 5}px`,
     },
     '& h2': {
       ...theme.typography.display1,
       color: theme.palette.text.secondary,
-      margin: '1em 0 0.7em',
+      margin: `${theme.spacing.unit * 4}px 0 ${theme.spacing.unit * 3}px`,
     },
     '& h3': {
       ...theme.typography.headline,
       color: theme.palette.text.secondary,
-      margin: '1em 0 0.7em',
+      margin: `${theme.spacing.unit * 4}px 0 ${theme.spacing.unit * 3}px`,
     },
     '& h4': {
       ...theme.typography.title,
       color: theme.palette.text.secondary,
-      margin: '1em 0 0.7em',
+      margin: `${theme.spacing.unit * 4}px 0 ${theme.spacing.unit * 3}px`,
     },
     '& p, & ul, & ol': {
       lineHeight: 1.6,
diff --git a/pages/_document.js b/pages/_document.js
index b621fb09449ce1..8f16ee9dca0b37 100644
--- a/pages/_document.js
+++ b/pages/_document.js
@@ -28,10 +28,6 @@ class MyDocument extends Document {
     return (
       <html lang="en" dir="ltr">
         <Head>
-          <meta
-            name="description"
-            content="React Components that Implement Google's Material Design."
-          />
           {/* Use minimum-scale=1 to enable GPU rasterization */}
           <meta
             name="viewport"
@@ -47,31 +43,13 @@ class MyDocument extends Document {
           <link rel="manifest" href="/static/manifest.json" />
           {/* PWA primary color */}
           <meta name="theme-color" content={pageContext.theme.palette.primary.main} />
+          <link rel="shortcut icon" href="/static/favicon.ico" />
+          <link rel="canonical" href={canonical} />
           <link
             rel="stylesheet"
             href="https://fonts.googleapis.com/css?family=Roboto:300,400,500"
           />
           <style id="insertion-point-jss" />
-          {/* Twitter */}
-          <meta name="twitter:card" content="summary" />
-          <meta name="twitter:site" content="@MaterialUI" />
-          <meta name="twitter:title" content="Material-UI" />
-          <meta
-            name="twitter:description"
-            content="React Components that Implement Google's Material Design."
-          />
-          <meta name="twitter:image" content="https://material-ui.com/static/brand.png" />
-          {/* Facebook */}
-          <meta property="og:type" content="website" />
-          <meta property="og:title" content="Material-UI" />
-          <meta
-            property="og:description"
-            content="React Components that Implement Google's Material Design."
-          />
-          <meta property="og:image" content="https://material-ui.com/static/brand.png" />
-          <meta property="og:locale" content="en_US" />
-          <link rel="shortcut icon" href="/static/favicon.ico" />
-          <link rel="canonical" href={canonical} />
         </Head>
         <body>
           <Main />
diff --git a/pages/index.js b/pages/index.js
index 8a0dab840ec981..f069e5551f314e 100644
--- a/pages/index.js
+++ b/pages/index.js
@@ -1,7 +1,6 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import compose from 'recompose/compose';
-import Head from 'next/head';
 import { withStyles } from '@material-ui/core/styles';
 import Typography from '@material-ui/core/Typography';
 import Button from '@material-ui/core/Button';
@@ -10,6 +9,7 @@ import HomeSteps from 'docs/src/modules/components/HomeSteps';
 import HomeBackers from 'docs/src/modules/components/HomeBackers';
 import HomeFooter from 'docs/src/modules/components/HomeFooter';
 import Link from 'docs/src/modules/components/Link';
+import Head from 'docs/src/modules/components/Head';
 
 const styles = theme => ({
   root: {
@@ -105,9 +105,7 @@ class HomePage extends React.Component {
             `,
           }}
         />
-        <Head>
-          <title>Material-UI</title>
-        </Head>
+        <Head />
         <div className={classes.hero}>
           <div className={classes.content}>
             <img
diff --git a/yarn.lock b/yarn.lock
index 815fb5e7d601c7..ab7cb4bd3dda81 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -10429,7 +10429,7 @@ typedarray@^0.0.6:
   version "0.0.6"
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
 
-typescript@^2.6.1:
+typescript@^2.8.0:
   version "2.9.2"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.9.2.tgz#1cbf61d05d6b96269244eb6a3bce4bd914e0f00c"