diff --git a/website/docs/contributing.md b/website/docs/contributing.md
index 86a93873fc..86bace34da 100644
--- a/website/docs/contributing.md
+++ b/website/docs/contributing.md
@@ -138,7 +138,7 @@ Please make sure the following is done when submitting a pull request:
 
 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `master`.
 2. Add the copyright notice to the top of any code new files you've added.
-3. Describe your [**test plan**](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md)!
+3. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md)!
 4. Make sure your code lints (`yarn prettier && yarn lint`).
 5. Make sure your Jest tests pass (`yarn test`).
 6. If you haven't already, [sign the CLA](https://code.facebook.com/cla).
diff --git a/website/docs/design-principles.md b/website/docs/design-principles.md
index 5593332c25..c04a3ed0f2 100644
--- a/website/docs/design-principles.md
+++ b/website/docs/design-principles.md
@@ -5,11 +5,11 @@ title: Design Principles
 
 _This section is a work in progress._
 
-- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8)
+- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
 - **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
 - **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
 - **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
-- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
+- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users.
 
 ## How Docusaurus works
 
diff --git a/website/docs/migration-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md
similarity index 99%
rename from website/docs/migration-from-v1-to-v2.md
rename to website/docs/migrating-from-v1-to-v2.md
index 0843f709f4..2c1626e587 100644
--- a/website/docs/migration-from-v1-to-v2.md
+++ b/website/docs/migrating-from-v1-to-v2.md
@@ -1,6 +1,6 @@
 ---
-id: migration-from-v1-to-v2
-title: Migration from v1 to v2
+id: migrating-from-v1-to-v2
+title: Migrating from v1 to v2
 ---
 
 This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index b89e26b769..741aa0ebdb 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -94,7 +94,7 @@ module.exports = {
             },
             {
               label: 'Migration from v1 to v2',
-              to: 'docs/migration-from-v1-to-v2',
+              to: 'docs/migrating-from-v1-to-v2',
             },
           ],
         },
diff --git a/website/sidebars.js b/website/sidebars.js
index b6be2a5a52..54d56c11cc 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -29,7 +29,7 @@ module.exports = {
       'using-plugins',
       'using-themes',
       'deployment',
-      'migration-from-v1-to-v2',
+      'migrating-from-v1-to-v2',
     ],
     'Advanced Guides': [
       'advanced-plugins',
diff --git a/website/src/pages/index.js b/website/src/pages/index.js
index 6a16bb0c7e..b34196d772 100644
--- a/website/src/pages/index.js
+++ b/website/src/pages/index.js
@@ -27,10 +27,8 @@ const QUOTES = [
         I've helped open source many projects at Facebook and every one
         needed a website. They all had very similar constraints: the
         documentation should be written in markdown and be deployed via GitHub
-        pages. None of the existing solutions were great, so I hacked my own and
-        then forked it whenever we needed a new website. I’m so glad that
-        Docusaurus now exists so that I don’t have to spend a week each time
-        spinning up a new one.
+        pages. I’m so glad that Docusaurus now exists so that I don’t have to
+        spend a week each time spinning up a new one.
       </>
     ),
   },
@@ -69,27 +67,25 @@ function Home() {
     <Layout
       permalink={'/'}
       description={'Easy to Maintain Open Source Documentation Websites'}>
-      <div className={styles['index-hero']}>
-        <div className={styles['index-hero-inner']}>
-          <h1 className={styles['index-hero-project-tagline']}>
+      <div className={styles.hero}>
+        <div className={styles.heroInner}>
+          <h1 className={styles.heroProjectTagline}>
             <img
               alt="Docusaurus with Keytar"
-              className={styles['index-hero-logo']}
+              className={styles.heroLogo}
               src={withBaseUrl('img/docusaurus_keytar.svg')}
             />
             {siteConfig.title} makes it easy to maintain{' '}
-            <span className={styles['index-hero-project-keywords']}>
-              Open Source
-            </span>{' '}
+            <span className={styles.heroProjectKeywords}>Open Source</span>{' '}
             documentation websites.
           </h1>
-          <div className={styles['index-ctas']}>
+          <div className={styles.indexCtas}>
             <Link
-              className={styles['index-ctas-get-started-button']}
+              className={styles.indexCtasGetStartedButton}
               to={withBaseUrl('docs/introduction')}>
               Get Started
             </Link>
-            <span className={styles['index-ctas-github-button']}>
+            <span className={styles.indexCtasGitHubButton}>
               <iframe
                 src="https://ghbtns.com/github-btn.html?user=facebook&amp;repo=docusaurus&amp;type=star&amp;count=true&amp;size=large"
                 frameBorder={0}
@@ -102,14 +98,24 @@ function Home() {
           </div>
         </div>
       </div>
-      <div className={styles['announcement']}>
-        <div className={styles['announcement-inner']}>
+      <div className={classnames(styles.announcement, styles.announcementDark)}>
+        <div className={styles.announcementInner}>
           We're working on{' '}
           <a href="https://github.com/facebook/docusaurus/issues/789">
             Docusaurus 2
           </a>
-          , contribute to its roadmap by suggesting features or giving{' '}
-          <Link to={withBaseUrl('/feedback')}>feedback here</Link>!
+          , contribute to its roadmap by suggesting features or giving feedback{' '}
+          <Link to={withBaseUrl('/feedback')}>here</Link>!
+        </div>
+      </div>
+      <div
+        className={classnames(styles.announcement, styles.announcementPrimary)}>
+        <div className={styles.announcementInner}>
+          Coming from v1? Check out our{' '}
+          <Link to={withBaseUrl('/docs/migrating-from-v1-to-v2')}>
+            v1 to v2 migration guide
+          </Link>
+          .
         </div>
       </div>
       <div className={styles.section}>
@@ -118,23 +124,24 @@ function Home() {
             <div className="col">
               <img
                 className={styles.featureImage}
-                alt={'Powered by Markdown'}
+                alt="Powered by MDX"
                 src={withBaseUrl('img/undraw_typewriter.svg')}
               />
-              <h3>Powered by Markdown</h3>
+              <h3 className="padding-top--md">Powered by Markdown</h3>
               <p className="padding-horiz--md">
                 Save time and focus on your project's documentation. Simply
-                write docs and blog posts with Markdown and Docusaurus will
-                publish a set of static html files ready to serve.
+                write docs and blog posts with Markdown/MDX and Docusaurus will
+                publish a set of static HTML files ready to serve. You can even
+                embed JSX components into your Markdown thanks to MDX.
               </p>
             </div>
             <div className="col">
               <img
-                alt={'Built Using React'}
+                alt="Built Using React"
                 className={styles.featureImage}
                 src={withBaseUrl('img/undraw_react.svg')}
               />
-              <h3>Built Using React</h3>
+              <h3 className="padding-top--md">Built Using React</h3>
               <p className="padding-horiz--md">
                 Extend or customize your project's layout by reusing React.
                 Docusaurus can be extended while reusing the same header and
@@ -143,11 +150,11 @@ function Home() {
             </div>
             <div className="col">
               <img
-                alt={'Ready for Translations'}
+                alt="Ready for Translations"
                 className={styles.featureImage}
                 src={withBaseUrl('img/undraw_around_the_world.svg')}
               />
-              <h3>Ready for Translations</h3>
+              <h3 className="padding-top--md">Ready for Translations</h3>
               <p className="padding-horiz--md">
                 Localization comes pre-configured. Use Crowdin to translate your
                 docs into over 70 languages.
@@ -159,11 +166,11 @@ function Home() {
           <div className="row">
             <div className="col col--4 col--offset-2">
               <img
-                alt={'Document Versioning'}
+                alt="Document Versioning"
                 className={styles.featureImage}
                 src={withBaseUrl('img/undraw_version_control.svg')}
               />
-              <h3>Document Versioning</h3>
+              <h3 className="padding-top--md">Document Versioning</h3>
               <p className="padding-horiz--md">
                 Support users on all versions of your project. Document
                 versioning helps you keep documentation in sync with project
@@ -172,11 +179,11 @@ function Home() {
             </div>
             <div className="col col--4">
               <img
-                alt={'Document Search'}
+                alt="Document Search"
                 className={styles.featureImage}
                 src={withBaseUrl('img/undraw_algolia.svg')}
               />
-              <h3>Document Search</h3>
+              <h3 className="padding-top--md">Document Search</h3>
               <p className="padding-horiz--md">
                 Make it easy for your community to find what they need in your
                 documentation. We proudly support Algolia documentation search.
@@ -202,7 +209,7 @@ function Home() {
                     img={quote.thumbnail}
                     style={{overflow: 'hidden'}}
                   />
-                  <div className="avatar__intro">
+                  <div className="avatar__intro padding-top--sm">
                     <h4 className="avatar__name">{quote.name}</h4>
                     <small className="avatar__subtitle">{quote.title}</small>
                   </div>
diff --git a/website/src/pages/styles.module.css b/website/src/pages/styles.module.css
index 7539423859..248cf68b97 100644
--- a/website/src/pages/styles.module.css
+++ b/website/src/pages/styles.module.css
@@ -19,12 +19,11 @@
 
 .featureImage {
   max-width: 60%;
+  max-height: 128px;
   margin: 0 auto;
 }
 
 .announcement {
-  background-color: #20232a;
-  color: #fff;
   font-weight: bold;
   font-size: 24px;
   padding: 48px;
@@ -32,29 +31,43 @@
   text-align: center;
 }
 
-.announcement-inner {
+.announcementDark {
+  background-color: #20232a;
+  color: #fff;
+}
+
+.announcementPrimary {
+  background-color: var(--ifm-color-primary);
+  color: #20232a;
+}
+
+.announcementPrimary a {
+  color: #fff;
+}
+
+.announcementInner {
   margin: 0 auto;
   max-width: 768px;
 }
 
-.index-hero {
+.hero {
   background-color: #2b3137;
   padding: 48px;
 }
 
-.index-hero-inner {
+.heroInner {
   margin: 0 auto;
   max-width: 1100px;
   padding: 0 20px;
 }
 
-.index-hero-project-tagline {
+.heroProjectTagline {
   color: #fff;
   font-size: 64px;
   margin: 0;
 }
 
-.index-hero-project-keywords {
+.heroProjectKeywords {
   color: var(--ifm-color-primary);
 }
 
@@ -79,7 +92,7 @@
   }
 }
 
-.index-hero-logo {
+.heroLogo {
   animation-duration: 2s;
   animation-name: jackInTheBox;
   float: right;
@@ -88,11 +101,11 @@
   background-color: #2b3137;
 }
 
-.index-ctas {
+.indexCtas {
   margin-top: 24px;
 }
 
-.index-ctas-get-started-button {
+.indexCtasGetStartedButton {
   border: 1px solid var(--ifm-color-primary);
   display: inline-block;
   line-height: 1.2em;
@@ -108,36 +121,36 @@
   padding: 18px 36px;
 }
 
-.index-ctas-github-button {
+.indexCtasGitHubButton {
   vertical-align: sub;
 }
 
 @media only screen and (max-width: 768px) {
-  .index-hero {
+  .hero {
     padding-left: 20px;
     padding-right: 20px;
   }
 
-  .index-hero-inner {
+  .heroInner {
     padding: 0;
   }
 
-  .index-hero-project-tagline {
+  .heroProjectTagline {
     font-size: 36px;
     text-align: center;
   }
 
-  .index-hero-logo {
+  .heroLogo {
     display: block;
     float: none;
     margin: 0 auto;
   }
 
-  .index-ctas {
+  .indexCtas {
     text-align: center;
   }
 
-  .index-ctas-github-button {
+  .indexCtasGitHubButton {
     display: none;
   }
 }