docs(v2): various improvements (#2768)

website/docs/blog.md

@@ -118,13 +118,13 @@ module.exports = {
 
 Accessing the feed:
 
-The feed for RSS can be found at
+The feed for RSS can be found at:
 
 ```text
 https://{your-domain}/blog/rss.xml
 ```
 
-and for atom
+and for Atom:
 
 ```text
 https://{your-domain}/blog/atom.xml
@@ -134,9 +134,7 @@ https://{your-domain}/blog/atom.xml
 
 ### 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.
-
-**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
+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.
 
 ```js {9} title="docusaurus.config.js"
 module.exports = {
@@ -155,6 +153,12 @@ module.exports = {
 };
 ```
 
+:::note
+
+Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
+
+:::
+
 <!--
 
 Adding a blog using the blog plugin.

website/docs/cli.md

@@ -44,8 +44,8 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
 
 | Name | Default | Description |
 | --- | --- | --- |
-| `--port` | `3000` | Specifies the port of the dev server |
-| `--host` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use `--host 0.0.0.0` |
+| `--port` | `3000` | Specifies the port of the dev server. |
+| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
 | `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
 | `--no-open` | `false` | Do not open automatically the page in the browser. |
 | `--poll` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
@@ -64,7 +64,7 @@ Compiles your site for production.
 
 | Name | Default | Description |
 | --- | --- | --- |
-| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
+| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). |
 | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
 | `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
 
@@ -81,7 +81,7 @@ Change any Docusaurus theme components to your liking with `docusaurus swizzle`.
 ```shell
 docusaurus swizzle <themeName> [componentName] [siteDir]
 
-# example (leaving out the siteDir to indicate this directory)
+# Example (leaving out the siteDir to indicate this directory)
 docusaurus swizzle @docusaurus/theme-classic DocSidebar
 ```
 
@@ -103,7 +103,7 @@ To learn more about swizzling, check [here](#).
 
 ### `docusaurus deploy`
 
-Deploys your site with [GitHub Pages](https://pages.github.com/).
+Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.md/#deploying-to-github-pages) for more details.
 
 #### Options
 

website/docs/configuration.md

@@ -15,10 +15,10 @@ However, it can be helpful if you have a high-level understanding of how the con
 
 The high-level overview of Docusaurus configuration can be categorized into:
 
-- [Site Metadata](#site-metadata)
-- [Deployment Configurations](#deployment-configurations)
-- [Theme, Plugin, and Preset Configurations](#theme-plugin-and-preset-configurations)
-- [Custom Configurations](#custom-configurations)
+- [Site metadata](#site-metadata)
+- [Deployment configurations](#deployment-configurations)
+- [Theme, plugin, and preset configurations](#theme-plugin-and-preset-configurations)
+- [Custom configurations](#custom-configurations)
 
 For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](docusaurus.config.js.md).
 
@@ -126,7 +126,7 @@ module.exports = {
 
 Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`.
 
-Basic Example:
+Basic example:
 
 ```jsx
 import React from 'react';

website/docs/creating-pages.md

@@ -63,7 +63,7 @@ In this component-based development era, it is encouraged to co-locate your styl
 - Add a `/src/pages/support.js` file
 - Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file.
 
-The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For e.g. a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`).
+The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`).
 
 ```sh
 my-website

website/docs/deployment.md

@@ -188,8 +188,8 @@ To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first
 
 ```js {2-3} title="docusaurus.config.js"
 module.exports = {
-  url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash
-  baseUrl: '/', // base directory of your site relative to your repo
+  url: 'https://docusaurus-2.netlify.com', // Url to your site with no trailing slash
+  baseUrl: '/', // Base directory of your site relative to your repo
   // ...
 };
 ```
@@ -223,7 +223,7 @@ Most importantly, however, deploying a Docusaurus project only takes a couple of
 npm i -g now
 ```
 
-2. Run a single command inside the root directory of your project:
+1. Run a single command inside the root directory of your project:
 
 ```bash
 now
@@ -239,9 +239,9 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w
 
 1. Create a new **Web Service** on Render, and give Render permission to access your Docusaurus repo.
 
-2. Select the branch to deploy. The default is `master`.
+1. Select the branch to deploy. The default is `master`.
 
-3. Enter the following values during creation.
+1. Enter the following values during creation.
 
    | Field                 | Value         |
    | --------------------- | ------------- |
@@ -263,13 +263,13 @@ Deploy your app in a matter of seconds using surge with the following steps:
 npm install --g surge
 ```
 
-2. To build the static files of your site for production in the root directory of your project, run:
+1. To build the static files of your site for production in the root directory of your project, run:
 
 ```bash
 npm run build
 ```
 
-3. Then, run this command inside the root directory of your project:
+1. Then, run this command inside the root directory of your project:
 
 ```bash
 surge build/

website/docs/docs.md

@@ -13,7 +13,7 @@ Every document has a unique `id`. By default, a document `id` is the name of the
 For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
 
 ```bash
-website # root directory of your site
+website # Root directory of your site
 └── docs
    ├── greeting.md
    └── guide
@@ -61,7 +61,7 @@ The document id of `_index` is reserved exclusively for the home doc page, so it
 
 :::note
 
-The page `docs` that you created (eg. `src/pages/docs.js`)  will take precedence over the route generated via the `homePageId` option.
+The page `docs` that you created (eg. `src/pages/docs.js`) will take precedence over the route generated via the `homePageId` option.
 
 :::
 
@@ -89,7 +89,7 @@ module.exports = {
 
 ### Sidebar object
 
-A sidebar object is defined like this.
+A sidebar object is defined like this:
 
 ```typescript
 type Sidebar = {
@@ -211,8 +211,8 @@ Sidebar item type that links to a non-document page. Example:
 ```js
 {
   type: 'link',
-  label: 'Custom Label', // string - the label that should be displayed.
-  href: 'https://example.com' // string - the target URL.
+  label: 'Custom Label', // The label that should be displayed (string).
+  href: 'https://example.com' // The target URL (string).
 }
 ```
 
@@ -230,7 +230,7 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example:
 ```js
 {
   type: 'ref',
-  id: 'doc1', // string - document id
+  id: 'doc1', // Document id (string).
 }
 ```
 

website/docs/docusaurus-core.md

@@ -191,7 +191,7 @@ function MyPage() {
 
 | Field | Description |
 | --- | --- |
-| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if SSR. |
+| `ExecutionEnvironment.canUseDOM` | `true` if on client, `false` if prerendering. |
 | `ExecutionEnvironment.canUseEventListeners` | `true` if on client and has `window.addEventListener`. |
 | `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. |
 | `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. |

website/docs/docusaurus.config.js.md

@@ -222,7 +222,7 @@ module.exports = {
 
 ### `customFields`
 
-Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
+Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.
 
 - Type: `Object`
 

website/docs/installation.md

@@ -64,8 +64,8 @@ my-website
 
 ### Project structure rundown
 
-- `/blog/` - Contains the blog markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md).
-- `/docs/` - Contains the markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](markdown-features.mdx).
+- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md).
+- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](markdown-features.mdx).
 - `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
   - `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](creating-pages.md).
 - `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory.

website/docs/introduction.md

@@ -4,13 +4,11 @@ title: Introduction
 description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
 ---
 
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
 ## Disclaimer
 
 It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:
 
-**You should use this if**
+**You should use this if:**
 
 - :white_check_mark: You want to contribute to Docusaurus 2
 - :white_check_mark: You want to build a modern website with client-side routing and prerendering
@@ -19,7 +17,7 @@ It has been a year since we made the first **alpha release** of Docusaurus 2 and
 - :white_check_mark: You want to ease the pain of migration in future
 - :white_check_mark: You do not need support for IE11
 
-**Do not use this if**
+**Do not use this if:**
 
 - :x: You need a fully production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
 - :x: You need the translation features present in v1
@@ -28,7 +26,7 @@ It has been a year since we made the first **alpha release** of Docusaurus 2 and
 
 ## A better Docusaurus is coming to town
 
-<img alt="Docusaurus " src={useBaseUrl('img/slash-introducing.svg')} />
+<img alt="Docusaurus " src={require('@docusaurus/useBaseUrl').default('img/slash-introducing.svg')} />
 
 Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).
 
@@ -44,8 +42,8 @@ Docusaurus is built with high attention to your experience building your site an
   - Extend and customize with React
   - Gain full control of your site's browsing experience by `swizzling` in your own components
 - **Pluggable**
-  - Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community.
-  - Open source your plugins to share with your fellow documentarians, because sharing is caring.
+  - Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
+  - Open source your plugins to share with your fellow documentarians, because sharing is caring
 - ✂️ **Developer experience**
   - Multiple bootstrapping templates to get your site up and running, start writing your docs right now
   - Universal configuration entry point to make it more maintainable by contributors

website/docs/lifecycle-apis.md

@@ -111,12 +111,12 @@ module.exports = function(context, options) {
     name: 'docusaurus-plugin',
     async contentLoaded({content, actions}) {
       const {createData, addRoute} = actions;
-      // create a data named 'prizes.json'
+      // Create a data named 'prizes.json'.
       const prizes = JSON.stringify(['$1', 'a cybertruck', 'nothing']);
       const prizesDataPath = await createData('prizes.json', prizes);
 
-      // add '/roll' page using 'website/src/component/roll.js` as the component
-      // and providing 'prizes' as props
+      // Add '/roll' page using 'website/src/component/roll.js` as the component
+      // and providing 'prizes' as props.
       addRoute({
         path: '/roll',
         component: '@site/src/components/roll.js',
@@ -201,7 +201,7 @@ module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
-      // Print out to console all the rendered routes
+      // Print out to console all the rendered routes.
       routesPaths.map((route) => {
         console.log(route);
       });
@@ -234,7 +234,7 @@ module.exports = function (context, options) {
 
 ## `injectHtmlTags()`
 
-Inject head and/or body html tags to Docusaurus generated html.
+Inject head and/or body HTML tags to Docusaurus generated HTML.
 
 ```typescript
 function injectHtmlTags(): {
@@ -247,7 +247,7 @@ type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
 
 interface HtmlTagObject {
   /**
-   * Attributes of the html tag
+   * Attributes of the HTML tag
    * E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
    */
   attributes?: {
@@ -368,22 +368,22 @@ module.exports = function (context, opts) {
     name: 'docusaurus-my-project-cool-plugin',
 
     async loadContent() {
-      // The loadContent hook is executed after siteConfig and env has been loaded
-      // You can return a JavaScript object that will be passed to contentLoaded hook
+      // The loadContent hook is executed after siteConfig and env has been loaded.
+      // You can return a JavaScript object that will be passed to contentLoaded hook.
     },
 
     async contentLoaded({content, actions}) {
-      // contentLoaded hook is done after loadContent hook is done
-      // actions are set of functional API provided by Docusaurus. e.g: addRoute
+      // The contentLoaded hook is done after loadContent hook is done.
+      // `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
     },
 
     async routesLoaded(routes) {
-      // routesLoaded hook is done after contentLoaded hook is done
+      // The routesLoaded hook is done after contentLoaded hook is done.
       // This can be useful if you need to change any route.
     },
 
     async postBuild(props) {
-      // after docusaurus <build> finish
+      // After docusaurus <build> finish.
     },
 
     // TODO
@@ -408,7 +408,7 @@ module.exports = function (context, opts) {
     },
 
     getPathsToWatch() {
-      // Path to watch
+      // Paths to watch.
     },
 
     getThemePath() {
@@ -423,11 +423,11 @@ module.exports = function (context, opts) {
     },
 
     extendCli(cli) {
-      // Register an extra command to enhance the CLI of docusaurus
+      // Register an extra command to enhance the CLI of Docusaurus
     },
 
     injectHtmlTags() {
-      // Inject head and/or body html tags
+      // Inject head and/or body HTML tags.
     },
   };
 };