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`:
```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 ''.
},
},
],

View file

@ -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>;

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:
```jsx
```jsx title="/src/pages/hello.js"
import React from 'react';
import Layout from '@theme/Layout';

View file

@ -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
...
// ...
};
```

View file

@ -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).
:::

View file

@ -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
```

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).
```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'],
...
// ...
}
```

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:
```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": {

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.
| 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:

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/).
```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

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.
```js {7-9} title="docusaurus.config.js"
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// highlight-start
theme: {
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/).
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"
/**
@ -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.
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/>
@ -142,10 +144,10 @@ npm install --save docusaurus-plugin-sass
```jsx {3} title="docusaurus.config.js"
module.exports = {
...
// ...
plugins: ['docusaurus-plugin-sass'],
...
}
// ...
};
```
3. Write and import your stylesheets in Sass/SCSS as normal.
@ -160,11 +162,11 @@ module.exports = {
[
'@docusaurus/preset-classic',
{
...
// ...
theme: {
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"
module.exports = {
...
// ...
themeConfig: {
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"
module.exports = {
...
// ...
themeConfig: {
// Relative to your site's "static" directory.
// Cannot be SVGs. Can be external URLs too.
image: 'img/docusaurus.png',
...
// ...
},
}
};
```
### 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"
module.exports = {
...
// ...
themeConfig: {
announcementBar: {
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`
textColor: '#091E42', // Defaults to `#000`
},
...
// ...
},
}
};
```
## 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"
module.exports = {
...
// ...
themeConfig: {
navbar: {
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)
},
},
...
// ...
},
}
};
```
### Navbar Links
@ -114,7 +115,7 @@ You can add links to the navbar via `themeConfig.navbar.links`:
```js {5-15} title="docusaurus.config.js"
module.exports = {
...
// ...
themeConfig: {
navbar: {
links: [
@ -129,9 +130,9 @@ module.exports = {
// ... other links
],
},
...
// ...
},
}
};
```
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"
module.exports = {
...
// ...
themeConfig: {
navbar: {
links: [
@ -163,9 +164,9 @@ module.exports = {
},
],
},
...
// ...
},
}
};
```
### 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"
module.exports = {
...
// ...
themeConfig: {
navbar: {
hideOnScroll: true,
},
...
// ...
},
}
};
```
## 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.
```js {4-5} title="docusaurus.config.js"
```js {5-6} title="docusaurus.config.js"
module.exports = {
// ...
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/github'),
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"
module.exports = {
...
// ...
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
...
// ...
},
};
```

View file

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

View file

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