docs(v2): proofread docs (#2527)

facebook · Apr 4, 2020 · 3dd83be · 3dd83be
1 parent 692ab14
commit 3dd83be
Show file tree

Hide file tree

Showing 14 changed files with 118 additions and 95 deletions.
diff --git a/website/docs/blog.md b/website/docs/blog.md
@@ -9,12 +9,19 @@ To setup your site's blog, start by creating a `blog` directory.
 
 Then, add a navbar link to your blog within `docusaurus.config.js`:
 
-```js
-links: [
-  ...
-  {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
-  ...
-]
+```js title="docusaurus.config.js"
+module.exports = {
+  themeConfig: {
+    // ...
+    navbar: {
+      links: [
+        // ...
+        // highlight-next-line
+        {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
+      ],
+    },
+  },
+};
 ```
 
 ## Adding posts
@@ -128,7 +135,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.
+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!
 
@@ -141,7 +148,7 @@ module.exports = {
       {
         blog: {
           path: './blog',
-          routeBasePath: '/', // Set this value to '/'.
+          routeBasePath: '', // Set this value to ''.
         },
       },
     ],

diff --git a/website/docs/configuration.md b/website/docs/configuration.md
@@ -109,14 +109,16 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
 
 Example:
 
-```js {3-6} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
 module.exports = {
-  ...
+  // ...
+  // highlight-start
   customFields: {
     image: '',
     keywords: [],
   },
-  ...
+  // highlight-end
+  // ...
 };
 ```
 
@@ -126,13 +128,16 @@ Your configuration object will be made available to all the components of your s
 
 Basic Example:
 
-```jsx {2,5-6}
+```jsx
 import React from 'react';
+// highlight-next-line
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 const Hello = () => {
+  // highlight-start
   const context = useDocusaurusContext();
   const {siteConfig = {}} = context;
+  // highlight-end
   const {title, tagline} = siteConfig;
 
   return <div>{`${title} · ${tagline}`}</div>;

diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md
@@ -13,7 +13,7 @@ The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
 
 In the `/src/pages/` directory, create a file called `hello.js` with the following contents:
 
-```jsx
+```jsx title="/src/pages/hello.js"
 import React from 'react';
 import Layout from '@theme/Layout';
 

diff --git a/website/docs/deployment.md b/website/docs/deployment.md
@@ -36,13 +36,13 @@ Example:
 
 ```jsx {3-6} title="docusaurus.config.js"
 module.exports = {
-  ...
+  // ...
   url: 'https://endiliey.github.io', // Your website URL
   baseUrl: '/',
   projectName: 'endiliey.github.io',
-  organizationName: 'endiliey'
-  ...
-}
+  organizationName: 'endiliey',
+  // ...
+};
 ```
 
 :::tip
@@ -119,7 +119,7 @@ To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first
 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
-  ...
+  // ...
 };
 ```
 

diff --git a/website/docs/docs.md b/website/docs/docs.md
@@ -44,7 +44,7 @@ module.exports = {
           // Sidebars filepath relative to the site dir.
           sidebarPath: require.resolve('./sidebars.js'),
         },
-        ...
+        // ...
       },
     ],
   ],
@@ -248,12 +248,12 @@ For sites with a sizable amount of content, we support the option to expand/coll
 
 ```js {4} title="docusaurus.config.js"
 module.exports = {
-  ...
+  // ...
   themeConfig: {
     sidebarCollapsible: false,
-    ...
+    // ...
   },
-}
+};
 ```
 
 ## Docs-only mode
@@ -271,7 +271,7 @@ module.exports = {
       {
         docs: {
           routeBasePath: '', // Set to empty string.
-          ...
+          // ...
         },
       },
     ],
@@ -280,7 +280,7 @@ module.exports = {
 };
 ```
 
-2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs.
+2. Set up a redirect to the initial document on the home page in `/src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs.
 
 ```jsx title="src/pages/index.js"
 import React from 'react';
@@ -299,6 +299,6 @@ Now, when visiting your site, it will show your initial document instead of a la
 
 :::tip
 
-There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode).
+There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `/src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode).
 
 :::
diff --git a/website/docs/installation.md b/website/docs/installation.md
@@ -107,12 +107,12 @@ Please update to the latest Docusaurus 2 version shown at the top of the page, n
 
 :::
 
-```json
-  "dependencies": {
-    "@docusaurus/core": "^2.0.0-alpha.49",
-    "@docusaurus/preset-classic": "^2.0.0-alpha.49",
-    ...
-  }
+```json title="package.json"
+"dependencies": {
+  "@docusaurus/core": "^2.0.0-alpha.49",
+  "@docusaurus/preset-classic": "^2.0.0-alpha.49",
+  // ...
+}
 ```
 
 Then, in the directory containing `package.json`, run your package manager's install command:
@@ -131,7 +131,7 @@ You should see the correct version as output.
 
 Alternatively, if you are using Yarn, you can do:
 
-```
+```bash
 yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
 ```
 

diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx
@@ -469,13 +469,13 @@ Code blocks within documentation are super-powered 💪.
 
 You can add a title to the code block by adding `title` key after the language (leave a space between them).
 
-    ```jsx title="src/components/HelloCodeTitle.js"
+    ```jsx title="/src/components/HelloCodeTitle.js"
     function HelloCodeTitle(props) {
       return <h1>Hello, {props.name}</h1>;
     }
     ```
 
-```jsx title="src/components/HelloCodeTitle.js"
+```jsx title="/src/components/HelloCodeTitle.js"
 function HelloCodeTitle(props) {
   return <h1>Hello, {props.name}</h1>;
 }
@@ -520,12 +520,12 @@ For example, if you want to add highlighting for the `powershell` language:
 
 ```js {5} title="docusaurus.config.js"
 module.exports = {
-  ...
+  // ...
   themeConfig: {
     prism: {
       additionalLanguages: ['powershell'],
     },
-    ...
+    // ...
   },
 };
 ```
@@ -672,9 +672,9 @@ You will also need to add the plugin to your `docusaurus.config.js`.
 
 ```js {3}
 module.exports = {
-  ...
+  // ...
   themes: ['@docusaurus/theme-live-codeblock'],
-  ...
+  // ...
 }
 ```
 

diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md
@@ -62,21 +62,21 @@ Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docus
 
 The `"scripts"` section of your `package.json` should be updated as follows:
 
-```json {3-6}
+```json {3-6} title="package.json"
 {
   "scripts": {
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy"
-    ...
+    // ...
   }
 }
 ```
 
 A typical Docusaurus 2 `package.json` may look like this:
 
-```json
+```json title="package.json"
 {
   "scripts": {
     "start": "docusaurus start",
@@ -112,7 +112,7 @@ If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of
 
 The `.gitignore` in your `website` should contain:
 
-```
+```bash title=".gitignore"
 # dependencies
 /node_modules
 
@@ -156,7 +156,7 @@ module.exports = {
           // sidebars file relative to website dir.
           sidebarPath: require.resolve('./sidebars.json'),
         },
-        ...
+        // ...
       },
     ],
   ],
@@ -245,7 +245,7 @@ module.exports = {
 
 In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
 
-```js
+```js title="siteConfig.js"
 headerIcon: 'img/docusaurus.svg',
 headerLinks: [
   { doc: "doc1", label: "Getting Started" },
@@ -428,7 +428,7 @@ In previous version, nested sidebar category is not allowed and sidebar category
 
 You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`.
 
-```js
+```js title="sidebars.json"
 {
 - type: 'subcategory',
 + type: 'category',
@@ -615,7 +615,7 @@ So v1 users need to migrate their versioned_sidebars file
 
 Example `versioned_sidebars/version-1.0.0-sidebars.json`:
 
-```json {2-3,5-6,9-10}
+```json {2-3,5-6,9-10}  title="versioned_sidebars/version-1.0.0-sidebars.json"
 {
 + "version-1.0.0/docs": {
 - "version-1.0.0-docs": {

diff --git a/website/docs/presets.md b/website/docs/presets.md
@@ -72,14 +72,14 @@ This is especially useful when some plugins and themes are intended to be used t
 
 The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
 
-| Themes                           | Plugins                             |
-| -------------------------------- | ----------------------------------- |
-| @docusaurus/theme-classic        | @docusaurus/plugin-content-docs     |
-| @docusaurus/theme-search-algolia | @docusaurus/plugin-content-blog     |
-|                                  | @docusaurus/plugin-content-pages    |
-|                                  | @docusaurus/plugin-google-analytics |
-|                                  | @docusaurus/plugin-google-gtag      |
-|                                  | @docusaurus/plugin-sitemap          |
+| Themes                             | Plugins                               |
+| ---------------------------------- | ------------------------------------- |
+| `@docusaurus/theme-classic`        | `@docusaurus/plugin-content-docs`     |
+| `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog`     |
+|                                    | `@docusaurus/plugin-content-pages`    |
+|                                    | `@docusaurus/plugin-google-analytics` |
+|                                    | `@docusaurus/plugin-google-gtag`      |
+|                                    | `@docusaurus/plugin-sitemap`          |
 
 To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
 

diff --git a/website/docs/search.md b/website/docs/search.md
@@ -18,16 +18,21 @@ Algolia DocSearch works by crawling the content of your website every 24 hours a
 
 To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://community.algolia.com/docsearch/).
 
-```jsx {3-8} title="docusaurus.config.js"
-themeConfig: {
+```jsx title="docusaurus.config.js"
+module.exports = {
+  // ...
+  themeConfig: {
     // ...
+    // highlight-start
     algolia: {
       appId: 'app-id',
       apiKey: 'api-key',
       indexName: 'index-name',
       algoliaOptions: {}, // Optional, if provided by Algolia
     },
+    // highlight-end
   },
+};
 ```
 
 ### Customizing the Algolia search bar