docs: various fixes and improvements (#3546)

README.md

@@ -31,9 +31,12 @@ Docusaurus is a project for building, deploying, and maintaining open source pro
 > Docusaurus is built in a way so that it can [get running](https://docusaurus.io/docs/en/installation/) in as little time as possible. We've built Docusaurus to handle the website build process so you can focus on your project.
 
 - **Localizable**
-  > Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation/) via CrowdIn. Empower and grow your international community by translating your documentation.
+
+> Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation/) via CrowdIn. Empower and grow your international community by translating your documentation.
+
 - **Customizable**
-  > While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/adding-blog/), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages/) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages/).
+
+> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/adding-blog/), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages/) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages/).
 
 ## Installation
 

admin/publish.md

@@ -157,7 +157,7 @@ npm access ls-packages
 </pre>
 </details>
 
-It can happen that some accesses not granted, as an admin might add you to the @docusaurus NPM organisation, but you don't have access to the packages that are not in that organisation.
+It can happen that some accesses not granted, as an admin might add you to the @docusaurus NPM organization, but you don't have access to the packages that are not in that organization.
 
 Please **double-check your permissions on these 3 packages**, otherwise you'll publish a half-release and will have to release a new version.
 
@@ -196,7 +196,7 @@ Now that the release is done, **merge the pull request**.
 
 ### 8. Notify people about new release (optional but desirable)
 
-After new release, it is cool to notify our users about this in the Dicsord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates.
+After new release, it is cool to notify our users about this in the Discord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates.
 
 For Discord:
 

packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.ts

@@ -7,7 +7,7 @@
 
 import {useState, useEffect, useCallback} from 'react';
 import useThemeConfig from '../../utils/useThemeConfig';
-import type {useAnnouncementBarReturns} from '@theme/hooks/useAnnoucementBar';
+import type {useAnnouncementBarReturns} from '@theme/hooks/useAnnouncementBar';
 
 const STORAGE_DISMISS_KEY = 'docusaurus.announcement.dismiss';
 const STORAGE_ID_KEY = 'docusaurus.announcement.id';

packages/docusaurus-theme-classic/src/types.d.ts

@@ -105,7 +105,7 @@ declare module '@theme/Heading' {
   export default Heading;
 }
 
-declare module '@theme/hooks/useAnnoucementBar' {
+declare module '@theme/hooks/useAnnouncementBar' {
   export type useAnnouncementBarReturns = {
     readonly isAnnouncementBarClosed: boolean;
     readonly closeAnnouncementBar: () => void;

website/docs/cli.md

@@ -97,7 +97,7 @@ Running the command will copy the relevant theme files to your site folder. You
 | `themeName`        | The name of the theme you are using.   |
 | `swizzleComponent` | The name of the component to swizzle.  |
 | `--danger`         | Allow swizzling of unstable components |
-| `--typescript`     | Swizzle typescript components          |
+| `--typescript`     | Swizzle TypeScript components          |
 
 To unswizzle a component, simply delete the files of the swizzled component.
 
@@ -130,6 +130,6 @@ Serve your built website locally.
 
 ### `docusaurus clear`
 
-Clear a Docusaurus site's generated assets, caches, build artifacts...
+Clear a Docusaurus site's generated assets, caches, build artifacts.
 
 We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.

website/docs/deployment.md

@@ -366,21 +366,21 @@ Deploy your app in a matter of seconds using surge with the following steps:
 npm install --g surge
 ```
 
-1. To build the static files of your site for production in the root directory of your project, run:
+2. To build the static files of your site for production in the root directory of your project, run:
 
 ```bash
 npm run build
 ```
 
-1. Then, run this command inside the root directory of your project:
+3. Then, run this command inside the root directory of your project:
 
 ```bash
 surge build/
 ```
 
 First-time users of Surge would be prompted to create an account from the command line(happens only once).
 
-Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given(which can be edited).
+Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given (which can be edited).
 
 ### Using your domain
 

website/docs/docusaurus-core.md

@@ -283,7 +283,7 @@ const MyComponent = () => {
 
 ### `useAllPluginInstancesData(pluginName: string)`
 
-Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by pluginId.
+Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
 
 Usage example:
 

website/docs/guides/creating-pages.md

@@ -70,7 +70,7 @@ In the same way, a page will be created at `http://localhost:3000/helloMarkdown`
 
 Markdown pages are less flexible than React pages, because it always uses the theme layout.
 
-Here's an [example markdown page](/examples/markdownPageExample).
+Here's an [example Markdown page](/examples/markdownPageExample).
 
 :::tip
 

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

@@ -361,7 +361,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
 
 #### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime`
 
-**BREAKING**: `editUrl` should point to (website) docusaurus project instead of `docs` directory.
+**BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory.
 
 Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
 
@@ -671,11 +671,11 @@ To use the migration command, follow these steps:
 
 2. To migrate your v1 website, run the migration command with the appropriate filesystem paths:
 
-```
-// migration command format
+```bash
+# migration command format
 npx @docusaurus/migrate migrate <v1 website directory> <desired v2 website directory>
 
-// example
+# example
 npx @docusaurus/migrate migrate ./v1-website ./v2-website
 ```
 
@@ -689,23 +689,23 @@ yarn start
 
 #### Options
 
-You can add option flags to the migration command to automatically migrate markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.
+You can add option flags to the migration command to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.
 
 | Name     | Description                                            |
 | -------- | ------------------------------------------------------ |
-| `--mdx`  | Add this flag to convert markdown to mdx automatically |
+| `--mdx`  | Add this flag to convert Markdown to MDX automatically |
 | `--page` | Add this flag to migrate pages automatically           |
 
-```
-// example using options
+```bash
+# example using options
 npx docusaurus-migrate migrate --mdx --page ./v1-website ./v2-website
 ```
 
 :::danger
 
 The migration of pages and MDX is still a work in progress.
 
-We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the --page and --mdx options.
+We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the `--page` and `--mdx` options.
 
 This way, you'd be able to easily inspect and fix the diff.
 

website/docs/introduction.md

@@ -7,7 +7,7 @@ slug: /
 
 ## 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:
+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:**
 

website/docs/lifecycle-apis.md

@@ -11,9 +11,9 @@ This section is a work in progress.
 
 Lifecycle APIs are shared by Themes and Plugins.
 
-## `validateOptions({options,validate})`
+## `validateOptions({options, validate})`
 
-Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during intialization.
+Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during initialization.
 
 ### `options`
 
@@ -61,7 +61,7 @@ export function validateOptions({options, validate}) {
 }
 ```
 
-## `validateThemeConfig({themeConfig,validate})`
+## `validateThemeConfig({themeConfig, validate})`
 
 Return validated and normalized configuration for the theme.
 
@@ -217,7 +217,7 @@ export default function friendsPlugin(context, options) {
         path: '/friends',
         component: '@site/src/components/Friends.js',
         modules: {
-          // propName -> json file path
+          // propName -> JSON file path
           friends: friendsJsonPath,
         },
         exact: true,
@@ -231,9 +231,9 @@ export default function friendsPlugin(context, options) {
 
 This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout.
 
-This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string)
+This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string).
 
-One this data is created, you can access it with the global data hooks APIs
+One this data is created, you can access it with the global data hooks APIs.
 
 :::caution
 

website/docs/markdown-features.mdx

@@ -282,7 +282,7 @@ import TabItem from '@theme/TabItem';
 </Tabs>;
 ```
 
-will result in
+And you will get the following:
 
 <Tabs
   defaultValue="apple"
@@ -848,46 +848,48 @@ Instead of implementing a dedicated component for multi-language support code bl
 
 The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is **intentional**. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
 
-    import Tabs from '@theme/Tabs';
-    import TabItem from '@theme/TabItem';
-
-    <Tabs
-      defaultValue="js"
-      values={[
-        { label: 'JavaScript', value: 'js', },
-        { label: 'Python', value: 'py', },
-        { label: 'Java', value: 'java', },
-      ]
-    }>
-    <TabItem value="js">
-
-    ```js
-    function helloWorld() {
-      console.log('Hello, world!');
-    }
-    ```
+````jsx
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-    </TabItem>
-    <TabItem value="py">
+<Tabs
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', },
+    { label: 'Python', value: 'py', },
+    { label: 'Java', value: 'java', },
+  ]
+}>
+<TabItem value="js">
 
-    ```py
-    def hello_world():
-      print 'Hello, world!'
-    ```
+```js
+function helloWorld() {
+  console.log('Hello, world!');
+}
+```
+
+</TabItem>
+<TabItem value="py">
 
-    </TabItem>
-    <TabItem value="java">
+```py
+def hello_world():
+  print 'Hello, world!'
+```
 
-    ```java
-    class HelloWorld {
-      public static void main(String args[]) {
-        System.out.println("Hello, World");
-      }
-    }
-    ```
+</TabItem>
+<TabItem value="java">
 
-    </TabItem>
-    </Tabs>
+```java
+class HelloWorld {
+  public static void main(String args[]) {
+    System.out.println("Hello, World");
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+````
 
 And you will get the following:
 
@@ -935,7 +937,7 @@ If you have multiple of these multi-language code tabs, and you want to sync the
 
 ## Assets
 
-Sometimes you want to link to static assets directly from markdown files, and it is convenient to co-locate the asset next to the markdown file using it.
+Sometimes you want to link to static assets directly from Markdown files, and it is convenient to co-locate the asset next to the markdown file using it.
 
 We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder.
 
@@ -955,7 +957,7 @@ Let's imagine the following file structure:
 You can use images in Markdown, or by requiring them and using a JSX image tag:
 
 ```mdx
-# My markdown page
+# My Markdown page
 
 <img src={require('./assets/docusaurus-asset-example-banner.png').default} />
 
@@ -967,7 +969,7 @@ or
 The ES imports syntax also works:
 
 ```mdx
-# My markdown page
+# My Markdown page
 
 import myImageUrl from './assets/docusaurus-asset-example-banner.png';
 
@@ -986,29 +988,29 @@ If you are using [@docusaurus/plugin-ideal-image](./using-plugins.md#docusaurusp
 
 ### Files
 
-In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc...
+In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc.
 
 ```mdx
-# My markdown page
+# My Markdown page
 
 <a
   target="_blank"
   href={require('./assets/docusaurus-asset-example-pdf.pdf').default}>
-  Download this PDF !!!
+  Download this PDF
 </a>
 
 or
 
-[Download this PDF using Markdown !!!](./assets/docusaurus-asset-example-pdf.pdf)
+[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf)
 ```
 
 <a
   target="_blank"
   href={require('./assets/docusaurus-asset-example-pdf.pdf').default}>
-  Download this PDF !!!
+  Download this PDF
 </a>
 
-[Download this PDF using Markdown !!!](./assets/docusaurus-asset-example-pdf.pdf)
+[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf)
 
 ### Inline SVGs
 

website/docs/using-themes.md

@@ -246,8 +246,8 @@ There are two lifecycle methods that are essential to theme implementation:
 
 These lifecycle method are not essential but recommended:
 
-- [`validateThemeConfig({themeConfig,validate})`](lifecycle-apis.md#validatethemeconfigthemeconfigvalidate)
-- [`validateOptions({options,validate})`](lifecycle-apis.md#validateoptionsoptionsvalidate)
+- [`validateThemeConfig({themeConfig, validate})`](lifecycle-apis.md#validatethemeconfigthemeconfig-validate)
+- [`validateOptions({options, validate})`](lifecycle-apis.md#validateoptionsoptions-validate)
 
 <!--
 

website/src/pages/examples/markdownPageExample.md

@@ -6,7 +6,7 @@ wrapperClassName: docusaurus-markdown-example
 
 # Markdown page
 
-This is a page generated from markdown to illustrate the markdown page feature.
+This is a page generated from markdown to illustrate the Markdown page feature.
 
 It supports all the regular MDX features, as you can see:
 

website/versioned_docs/version-2.0.0-alpha.60/deployment.md

@@ -335,7 +335,7 @@ surge build/
 
 First-time users of Surge would be prompted to create an account from the command line(happens only once).
 
-Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given(which can be edited).
+Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given (which can be edited).
 
 ### Using your domain