docs(v2): misc update

website/docs/blog.md

@@ -23,7 +23,7 @@ To publish in the blog, create a file within the blog directory with a formatted
 
 For example, at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
 
-```yml
+```md
 ---
 title: Welcome Docusaurus v2
 author: Dattatreya Tripathy
@@ -33,8 +33,7 @@ authorTwitter: CuriousDT
 tags: [hello, docusaurus-v2]
 ---
 
-Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**]
-(https://v2.docusaurus.io/).
+Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/).
 
 <!--truncate-->
 
@@ -57,7 +56,7 @@ The only required field is `title`; however, we provide options to add author in
 
 Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
 
-```yml
+```md
 ---
 title: Truncation Example
 ---
@@ -79,9 +78,11 @@ Or this.
 
 ### Blog-only mode
 
-You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. Make sure there's no `index.js` page in `src/pages` or else there could be a conflict of paths!
+You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
 
-```diff
+**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
+
+```js
 // docusaurus.config.js
 module.exports = {
   // ...
@@ -91,7 +92,7 @@ module.exports = {
       {
         blog: {
           path: './blog',
-+         routeBasePath: '/',
+          routeBasePath: '/', // Set this value to '/'.
         },
       },
     ],
@@ -99,7 +100,6 @@ module.exports = {
 };
 ```
 
-
 <!--
 
 Adding a blog using the blog plugin.

website/docs/migrating-from-v1-to-v2.md

@@ -20,7 +20,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
     └── static
 ```
 
-## Step 1 - Update `package.json`
+## Update `package.json`
 
 ### Scoped package names
 
@@ -88,7 +88,7 @@ A typical Docusaurus 2 `package.json` may look like this:
 }
 ```
 
-## Step 2 - Migrate `siteConfig` to `docusaurus.config.js`
+## Migrate `siteConfig` to `docusaurus.config.js`
 
 Rename `siteConfig.js` to `docusaurus.config.js`. In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a `@docusaurus/preset-classic` preset which bundles most of the essential plugins present in Docusaurus 1.
 
@@ -103,9 +103,9 @@ module.exports = {
       '@docusaurus/preset-classic',
       {
         docs: {
-          // docs folder path relative to site dir.
+          // docs folder path relative to website dir.
           path: '../docs',
-          // sidebars file relative to site dir.
+          // sidebars file relative to website dir.
           sidebarPath: require.resolve('./sidebars.json'),
         },
         ...
@@ -357,7 +357,7 @@ The following fields are all deprecated, you may remove from your configuration
 
 We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
 
-## Step 3 - Delete footer file
+## Delete footer file
 
 `website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
 
@@ -367,13 +367,23 @@ yarn swizzle @docusaurus/theme-classic Footer
 
 This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, you may then edit this component for customization.
 
-## Step 4 - Update your page files
+## Update your page files
 
 Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, you can notice that we have to move `pages/en` files in v1 to `src/pages` instead.
 
 `CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website to see what styles are available).
 
-## Step 5 - Modify `.gitignore`
+## Update your docs
+
+### Update syntax
+
+In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common examples is that self-closing tags like `<img>` and `<br>` would have to be explicitly closed now: `<img/>` and `<br/>`. The tags have to be valid JSX.
+
+### Language-specific Code Tabs
+
+Not yet supported. Stay tuned.
+
+## Modify `.gitignore`
 
 The `.gitignore` in your `website` should contain:
 
@@ -400,7 +410,7 @@ yarn-debug.log*
 yarn-error.log*
 ```
 
-## Step 6 - Test your site
+## Test your site
 
 After migration, your folder structure should look like this:
 
@@ -428,6 +438,10 @@ cd website
 yarn start
 ```
 
-## Step 7 - Configure your build directory
+## Configure your `build` directory
 
 In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. However, in Docusaurus 2, it is now moved to just `website/build`. Make sure that you update your deployment configuration to read the generated files from the correct `build` directory.
+
+## Support
+
+For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord channel](https://discordapp.com/invite/kYaNd6V). Feel free to tag us ([@yangshun](https://github.com/yangshun) and [@endiliey](https://github.com/endiliey)) in any migration PRs if you would like us to have a look.

website/docs/sidebar.md

@@ -33,8 +33,8 @@ A sidebar object looks like the following. The key `docs` is the name of the sid
 module.exports = {
   docs: {
     'Getting started': ['greeting'],
-    'Docusaurus': ['doc1'],
-  }
+    Docusaurus: ['doc1'],
+  },
 };
 ```
 
@@ -47,20 +47,21 @@ module.exports = {
     {
       type: 'category',
       label: 'Getting Started',
-      items: ['greeting']
+      items: ['greeting'],
     },
     {
       type: 'category',
       label: 'Docusaurus',
-      items: ['doc1']
+      items: ['doc1'],
     },
-  ]
+  ],
 };
 ```
 
 You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
 
 Example:
+
 ```js
 // sidebars.js
 module.exports = {
@@ -70,7 +71,7 @@ module.exports = {
   secondSidebar: {
     'Category A': ['doc2'],
     'Category B': ['doc3'],
-  }
+  },
 };
 ```
 
@@ -94,6 +95,7 @@ However, the last part of the `id` can be defined by user in the frontmatter. Fo
 ---
 id: part1
 ---
+
 Lorem ipsum
 ```
 
@@ -120,7 +122,7 @@ Sidebar item type that links to a doc page. Example:
 Using just the [Document ID](#document-id) is perfectly valid as well, the following is equivalent to the above:
 
 ```js
-'doc1' // string - document id
+'doc1'; // string - document id
 ```
 
 Note that using this type will bind the linked doc to current sidebar, this means that if you access `doc1` page, the sidebar displayed will be the sidebar this item is on. For below case, `doc1` is bounded to `firstSidebar`.
@@ -134,11 +136,10 @@ module.exports = {
   secondSidebar: {
     'Category A': ['doc2'],
     'Category B': ['doc3'],
-  }
+  },
 };
 ```
 
-
 ### Link
 
 Sidebar item type that links to a non-document page. Example:

website/docs/styling-layout.md

@@ -50,7 +50,7 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
 }
 ```
 
-In future, we will provide an easier way to generate the different shades of colors.
+Infima uses 7 shades of each color. We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color. In future, we will provide an easier way to generate the different shades of colors.
 
 <!-- TODO need more refinement here -->