docs(v2): proofread docs (#2527)

This commit is contained in:
Yangshun Tay 2020-04-04 14:05:59 +08:00 committed by GitHub
parent 692ab14e4f
commit 3dd83be988
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 118 additions and 95 deletions

View file

@ -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`: Then, add a navbar link to your blog within `docusaurus.config.js`:
```js ```js title="docusaurus.config.js"
links: [ module.exports = {
... themeConfig: {
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' // ...
... navbar: {
] links: [
// ...
// highlight-next-line
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
``` ```
## Adding posts ## Adding posts
@ -128,7 +135,7 @@ https://{your-domain}/blog/atom.xml
### Blog-only mode ### 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! **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: { blog: {
path: './blog', path: './blog',
routeBasePath: '/', // Set this value to '/'. routeBasePath: '', // Set this value to ''.
}, },
}, },
], ],

View file

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

View file

@ -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: 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 React from 'react';
import Layout from '@theme/Layout'; import Layout from '@theme/Layout';

View file

@ -36,13 +36,13 @@ Example:
```jsx {3-6} title="docusaurus.config.js" ```jsx {3-6} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
url: 'https://endiliey.github.io', // Your website URL url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/', baseUrl: '/',
projectName: 'endiliey.github.io', projectName: 'endiliey.github.io',
organizationName: 'endiliey' organizationName: 'endiliey',
... // ...
} };
``` ```
:::tip :::tip
@ -119,7 +119,7 @@ To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first
module.exports = { module.exports = {
url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash
baseUrl: '/', // base directory of your site relative to your repo baseUrl: '/', // base directory of your site relative to your repo
... // ...
}; };
``` ```

View file

@ -44,7 +44,7 @@ module.exports = {
// Sidebars filepath relative to the site dir. // Sidebars filepath relative to the site dir.
sidebarPath: require.resolve('./sidebars.js'), 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" ```js {4} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
sidebarCollapsible: false, sidebarCollapsible: false,
... // ...
}, },
} };
``` ```
## Docs-only mode ## Docs-only mode
@ -271,7 +271,7 @@ module.exports = {
{ {
docs: { docs: {
routeBasePath: '', // Set to empty string. 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" ```jsx title="src/pages/index.js"
import React from 'react'; import React from 'react';
@ -299,6 +299,6 @@ Now, when visiting your site, it will show your initial document instead of a la
:::tip :::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).
::: :::

View file

@ -107,12 +107,12 @@ Please update to the latest Docusaurus 2 version shown at the top of the page, n
::: :::
```json ```json title="package.json"
"dependencies": { "dependencies": {
"@docusaurus/core": "^2.0.0-alpha.49", "@docusaurus/core": "^2.0.0-alpha.49",
"@docusaurus/preset-classic": "^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: 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: 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 yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
``` ```

View file

@ -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). 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) { function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>; return <h1>Hello, {props.name}</h1>;
} }
``` ```
```jsx title="src/components/HelloCodeTitle.js" ```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) { function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>; 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" ```js {5} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
prism: { prism: {
additionalLanguages: ['powershell'], additionalLanguages: ['powershell'],
}, },
... // ...
}, },
}; };
``` ```
@ -672,9 +672,9 @@ You will also need to add the plugin to your `docusaurus.config.js`.
```js {3} ```js {3}
module.exports = { module.exports = {
... // ...
themes: ['@docusaurus/theme-live-codeblock'], themes: ['@docusaurus/theme-live-codeblock'],
... // ...
} }
``` ```

View file

@ -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: The `"scripts"` section of your `package.json` should be updated as follows:
```json {3-6} ```json {3-6} title="package.json"
{ {
"scripts": { "scripts": {
"start": "docusaurus start", "start": "docusaurus start",
"build": "docusaurus build", "build": "docusaurus build",
"swizzle": "docusaurus swizzle", "swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy" "deploy": "docusaurus deploy"
... // ...
} }
} }
``` ```
A typical Docusaurus 2 `package.json` may look like this: A typical Docusaurus 2 `package.json` may look like this:
```json ```json title="package.json"
{ {
"scripts": { "scripts": {
"start": "docusaurus start", "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: The `.gitignore` in your `website` should contain:
``` ```bash title=".gitignore"
# dependencies # dependencies
/node_modules /node_modules
@ -156,7 +156,7 @@ module.exports = {
// sidebars file relative to website dir. // sidebars file relative to website dir.
sidebarPath: require.resolve('./sidebars.json'), sidebarPath: require.resolve('./sidebars.json'),
}, },
... // ...
}, },
], ],
], ],
@ -245,7 +245,7 @@ module.exports = {
In Docusaurus 1, header icon and header links were root fields in `siteConfig`: In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
```js ```js title="siteConfig.js"
headerIcon: 'img/docusaurus.svg', headerIcon: 'img/docusaurus.svg',
headerLinks: [ headerLinks: [
{ doc: "doc1", label: "Getting Started" }, { 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`. 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: 'subcategory',
+ type: 'category', + 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`: 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": {
- "version-1.0.0-docs": { - "version-1.0.0-docs": {

View file

@ -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. The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
| Themes | Plugins | | Themes | Plugins |
| -------------------------------- | ----------------------------------- | | ---------------------------------- | ------------------------------------- |
| @docusaurus/theme-classic | @docusaurus/plugin-content-docs | | `@docusaurus/theme-classic` | `@docusaurus/plugin-content-docs` |
| @docusaurus/theme-search-algolia | @docusaurus/plugin-content-blog | | `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog` |
| | @docusaurus/plugin-content-pages | | | `@docusaurus/plugin-content-pages` |
| | @docusaurus/plugin-google-analytics | | | `@docusaurus/plugin-google-analytics` |
| | @docusaurus/plugin-google-gtag | | | `@docusaurus/plugin-google-gtag` |
| | @docusaurus/plugin-sitemap | | | `@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: 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:

View file

@ -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/). 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" ```jsx title="docusaurus.config.js"
themeConfig: { module.exports = {
// ...
themeConfig: {
// ... // ...
// highlight-start
algolia: { algolia: {
appId: 'app-id', appId: 'app-id',
apiKey: 'api-key', apiKey: 'api-key',
indexName: 'index-name', indexName: 'index-name',
algoliaOptions: {}, // Optional, if provided by Algolia algoliaOptions: {}, // Optional, if provided by Algolia
}, },
// highlight-end
}, },
};
``` ```
### Customizing the Algolia search bar ### Customizing the Algolia search bar

View file

@ -10,16 +10,18 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset. If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset.
```js {7-9} title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ... // ...
presets: [ presets: [
[ [
'@docusaurus/preset-classic', '@docusaurus/preset-classic',
{ {
// highlight-start
theme: { theme: {
customCss: require.resolve('./src/css/custom.css'), customCss: require.resolve('./src/css/custom.css'),
}, },
// highlight-end
}, },
], ],
], ],
@ -32,7 +34,7 @@ Any CSS you write within that file will be available globally and can be referen
`@docusaurus/preset-classic` uses [Infima](https://facebookincubator.github.io/infima/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://facebookincubator.github.io/infima/). `@docusaurus/preset-classic` uses [Infima](https://facebookincubator.github.io/infima/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://facebookincubator.github.io/infima/).
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file. When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file.
```css title="/src/css/custom.css" ```css title="/src/css/custom.css"
/** /**
@ -53,7 +55,7 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
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. 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.
Alternatively, use the following tool to generate the different shades for your website and copy the variables into `src/css/custom.css`. Alternatively, use the following tool to generate the different shades for your website and copy the variables into `/src/css/custom.css`.
<ColorGenerator/> <ColorGenerator/>
@ -142,10 +144,10 @@ npm install --save docusaurus-plugin-sass
```jsx {3} title="docusaurus.config.js" ```jsx {3} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
plugins: ['docusaurus-plugin-sass'], plugins: ['docusaurus-plugin-sass'],
... // ...
} };
``` ```
3. Write and import your stylesheets in Sass/SCSS as normal. 3. Write and import your stylesheets in Sass/SCSS as normal.
@ -160,11 +162,11 @@ module.exports = {
[ [
'@docusaurus/preset-classic', '@docusaurus/preset-classic',
{ {
... // ...
theme: { theme: {
customCss: require.resolve('./src/css/custom.scss'), customCss: require.resolve('./src/css/custom.scss'),
}, },
... // ...
}, },
], ],
], ],

View file

@ -17,10 +17,10 @@ To remove the ability to switch on dark mode, there is an option `themeConfig.di
```js {4} title="docusaurus.config.js" ```js {4} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
disableDarkMode: false, disableDarkMode: false,
... // ...
}, },
}; };
``` ```
@ -31,14 +31,14 @@ You can configure a default image that will be used for your meta tag, in partic
```js {4-6} title="docusaurus.config.js" ```js {4-6} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
// Relative to your site's "static" directory. // Relative to your site's "static" directory.
// Cannot be SVGs. Can be external URLs too. // Cannot be SVGs. Can be external URLs too.
image: 'img/docusaurus.png', image: 'img/docusaurus.png',
... // ...
}, },
} };
``` ```
### Announcement bar ### Announcement bar
@ -47,17 +47,18 @@ Sometimes you want to announce something in your website. Just for such a case,
```js {4-9} title="docusaurus.config.js" ```js {4-9} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
announcementBar: { announcementBar: {
id: 'support_us', // Any value that will identify this message id: 'support_us', // Any value that will identify this message
content: 'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>', content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc', // Defaults to `#fff` backgroundColor: '#fafbfc', // Defaults to `#fff`
textColor: '#091E42', // Defaults to `#000` textColor: '#091E42', // Defaults to `#000`
}, },
... // ...
}, },
} };
``` ```
## Hooks ## Hooks
@ -91,7 +92,7 @@ To improve dark mode support, you can also set a different logo for this mode.
```js {5-11} title="docusaurus.config.js" ```js {5-11} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
navbar: { navbar: {
title: 'Site Title', title: 'Site Title',
@ -103,9 +104,9 @@ module.exports = {
target: '_self', // by default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one) target: '_self', // by default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one)
}, },
}, },
... // ...
}, },
} };
``` ```
### Navbar Links ### Navbar Links
@ -114,7 +115,7 @@ You can add links to the navbar via `themeConfig.navbar.links`:
```js {5-15} title="docusaurus.config.js" ```js {5-15} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
navbar: { navbar: {
links: [ links: [
@ -129,9 +130,9 @@ module.exports = {
// ... other links // ... other links
], ],
}, },
... // ...
}, },
} };
``` ```
Outbound links automatically get `target="_blank" rel="noopener noreferrer"` attributes. Outbound links automatically get `target="_blank" rel="noopener noreferrer"` attributes.
@ -142,7 +143,7 @@ Navbar items can also be dropdown items by specifying the `items`, an inner arra
```js {9-19} title="docusaurus.config.js" ```js {9-19} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
navbar: { navbar: {
links: [ links: [
@ -163,9 +164,9 @@ module.exports = {
}, },
], ],
}, },
... // ...
}, },
} };
``` ```
### Auto-hide sticky navbar ### Auto-hide sticky navbar
@ -174,14 +175,14 @@ You can enable this cool UI feature that automatically hides the navbar when a u
```js {5} title="docusaurus.config.js" ```js {5} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
navbar: { navbar: {
hideOnScroll: true, hideOnScroll: true,
}, },
... // ...
}, },
} };
``` ```
## Footer ## Footer
@ -194,13 +195,15 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.
```js {4-5} title="docusaurus.config.js" ```js {5-6} title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
prism: { prism: {
theme: require('prism-react-renderer/themes/github'), theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'), darkTheme: require('prism-react-renderer/themes/dracula'),
}, },
// ...
}, },
}; };
``` ```
@ -213,12 +216,12 @@ You can set a default language for code blocks if no language is added after the
```js {5} title="docusaurus.config.js" ```js {5} title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
themeConfig: { themeConfig: {
prism: { prism: {
defaultLanguage: 'javascript', defaultLanguage: 'javascript',
}, },
... // ...
}, },
}; };
``` ```

View file

@ -400,12 +400,13 @@ npm install --save @docusaurus/plugin-ideal-image
Modify your `docusaurus.config.js` Modify your `docusaurus.config.js`
```diff ```js title="docusaurus.config.js"
module.exports = { module.exports = {
... // ...
+ plugins: ['@docusaurus/plugin-ideal-image'], // highlight-next-line
... plugins: ['@docusaurus/plugin-ideal-image'],
} // ...
};
``` ```
#### Usage #### Usage

View file

@ -161,8 +161,8 @@ website
There are two lifecycle methods that are essential to theme implementation: There are two lifecycle methods that are essential to theme implementation:
- [getThemePath](lifecycle-apis.md#getthemepath) - [`getThemePath()`](lifecycle-apis.md#getthemepath)
- [getClientModules](lifecycle-apis.md#getclientmodules) - [`getClientModules()`](lifecycle-apis.md#getclientmodules)
<!-- <!--