mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-11 16:17:25 +02:00
docs: audit grammar issues (#6203)
* docs: audit grammar mistakes * fix code block language * revert change * let's get another
This commit is contained in:
Joshua Chen
GitHub
parent
3195e7feed
commit
73ee356949
56 changed files with 432 additions and 383 deletions
|
|
@ -76,7 +76,7 @@ module.exports = {
|
|||
|
||||
- Type: `string`
|
||||
|
||||
Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
|
||||
Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -90,9 +90,7 @@ module.exports = {
|
|||
|
||||
- Type: `string | undefined`
|
||||
|
||||
Path to your site favicon
|
||||
|
||||
Example, if your favicon is in `static/img/favicon.ico`:
|
||||
Path to your site favicon. For example, if your favicon is in `static/img/favicon.ico`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -112,7 +110,7 @@ Allow to customize the presence/absence of a trailing slash at the end of URLs/l
|
|||
|
||||
:::tip
|
||||
|
||||
Each static hosting provider serve static files differently (this behavior may even change over time).
|
||||
Each static hosting provider serves static files differently (this behavior may even change over time).
|
||||
|
||||
Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting.
|
||||
|
||||
|
|
@ -146,7 +144,7 @@ module.exports = {
|
|||
```
|
||||
|
||||
- `label`: the label to use for this locale
|
||||
- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Araric, Hebrew, etc.)
|
||||
- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Arabic, Hebrew, etc.)
|
||||
|
||||
### `noIndex` {#noindex}
|
||||
|
||||
|
|
@ -341,33 +339,45 @@ module.exports = {
|
|||
|
||||
### `plugins` {#plugins}
|
||||
|
||||
<!-- TODO: configuration for plugins -->
|
||||
- Type: `PluginConfig[]`
|
||||
|
||||
- Type: `any[]`
|
||||
```ts
|
||||
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
|
||||
```
|
||||
|
||||
See [plugin method references](./plugin-methods/README.md) for the shape of a `PluginModule`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [],
|
||||
plugins: [
|
||||
'docusaurus-plugin-awesome',
|
||||
['docusuarus-plugin-confetti', {fancy: false}],
|
||||
() => ({
|
||||
postBuild() {
|
||||
console.log('Build finished');
|
||||
},
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### `themes` {#themes}
|
||||
|
||||
<!-- TODO: configuration for plugins -->
|
||||
|
||||
- Type: `any[]`
|
||||
- Type: `PluginConfig[]`
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themes: [],
|
||||
themes: ['@docusaurus/theme-classic'],
|
||||
};
|
||||
```
|
||||
|
||||
### `presets` {#presets}
|
||||
|
||||
<!-- TODO: configuration for presets -->
|
||||
- Type: `PresetConfig[]`
|
||||
|
||||
- Type: `any[]`
|
||||
```ts
|
||||
type PresetConfig = string | [string, any];
|
||||
```
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -390,7 +400,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
Attempting to add unknown field in the config will lead to error in build time:
|
||||
Attempting to add unknown fields in the config will lead to errors during build time:
|
||||
|
||||
```bash
|
||||
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
|
||||
|
|
@ -548,7 +558,7 @@ module.exports = {
|
|||
|
||||
:::caution
|
||||
|
||||
This banner need to inline CSS / JS.
|
||||
This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL.
|
||||
|
||||
If you have a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), you should rather disable it.
|
||||
|
||||
|
|
|
|||
|
|
@ -37,11 +37,11 @@ interface LoadContext {
|
|||
|
||||
`options` are the [second optional parameter when the plugins are used](../../using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. If there's a [`validateOptions`](./static-methods.md#validateOptions) function exported, the `options` will be validated and normalized beforehand.
|
||||
|
||||
Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
|
||||
Alternatively, if a preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to the individual plugin to define what options it takes.
|
||||
|
||||
## Example {#example}
|
||||
|
||||
Here's a mind model for a presumptuous plugin implementation.
|
||||
Here's a mental model for a presumptuous plugin implementation.
|
||||
|
||||
```js
|
||||
// A JavaScript function that returns an object.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,9 @@ Docusaurus has some infrastructure like hot reloading, CLI, and swizzling, that
|
|||
|
||||
## `getPathsToWatch()` {#getPathsToWatch}
|
||||
|
||||
Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site. Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server.
|
||||
Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site.
|
||||
|
||||
Use this for files that are consumed server-side, because theme files are automatically watched by Webpack dev server.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -27,7 +29,7 @@ module.exports = function (context, options) {
|
|||
|
||||
## `extendCli(cli)` {#extendCli}
|
||||
|
||||
Register an extra command to enhance the CLI of Docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander/v/5.1.0) object.
|
||||
Register an extra command to enhance the CLI of Docusaurus. `cli` is a [commander](https://www.npmjs.com/package/commander/v/5.1.0) object.
|
||||
|
||||
:::caution
|
||||
|
||||
|
|
@ -55,7 +57,7 @@ module.exports = function (context, options) {
|
|||
|
||||
## `getThemePath()` {#getThemePath}
|
||||
|
||||
Returns the path to the directory where the theme components can be found. When your users calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
|
||||
Returns the path to the directory where the theme components can be found. When your users call `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
|
||||
|
||||
For example, your `getThemePath` can be:
|
||||
|
||||
|
|
@ -74,7 +76,7 @@ module.exports = function (context, options) {
|
|||
|
||||
## `getTypeScriptThemePath()` {#getTypeScriptThemePath}
|
||||
|
||||
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make path returned by `getThemePath()` be the compiled JavaScript output.
|
||||
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement for `getThemePath()`. Typically, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make the path returned by `getThemePath()` be the compiled JavaScript output.
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
@ -108,7 +110,7 @@ module.exports = function (context, options) {
|
|||
|
||||
**This is a static method, not attached to any plugin instance.**
|
||||
|
||||
Returns a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all component are considered stable.
|
||||
Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without `--danger`. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all components are considered stable.
|
||||
|
||||
```js {0-12} title="my-theme/src/index.js"
|
||||
const swizzleAllowedComponents = [
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ module.exports = function (context, options) {
|
|||
|
||||
Themes using the `<Translate>` API can provide default code translation messages.
|
||||
|
||||
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site current locale.
|
||||
It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site's current locale.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ toc_max_heading_level: 4
|
|||
|
||||
# Lifecycle APIs
|
||||
|
||||
During build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files.
|
||||
During the build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files.
|
||||
|
||||
## `async loadContent()` {#loadContent}
|
||||
|
||||
|
|
@ -63,9 +63,9 @@ type Module =
|
|||
|
||||
#### `createData(name: string, data: any): Promise<string>` {#createData}
|
||||
|
||||
A declarative callback to create static data (generally json or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
|
||||
A declarative callback to create static data (generally JSON or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
|
||||
|
||||
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
|
||||
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
|
||||
|
||||
```jsx title="website/src/components/Friends.js"
|
||||
import React from 'react';
|
||||
|
|
@ -105,7 +105,7 @@ export default function friendsPlugin(context, options) {
|
|||
|
||||
#### `setGlobalData(data: any): void`
|
||||
|
||||
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 function permits one 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 becomes accessible to your client-side/theme code through the [`useGlobalData`](../../docusaurus-core.md#useGlobalData) and [`usePluginData`](../../docusaurus-core.md#usePluginData) hooks.
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ Global data is... global: its size affects the loading time of all pages of your
|
|||
|
||||
:::
|
||||
|
||||
For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
|
||||
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
|
||||
|
||||
```jsx title="website/src/components/Friends.js"
|
||||
import React from 'react';
|
||||
|
|
@ -174,7 +174,7 @@ The API of `configureWebpack` will be modified in the future to accept an object
|
|||
|
||||
You may use them to return your webpack configures conditionally.
|
||||
|
||||
For example, this plugin below modify the webpack config to transpile `.foo` file.
|
||||
For example, this plugin below modify the webpack config to transpile `.foo` files.
|
||||
|
||||
```js title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function (context, options) {
|
||||
|
|
@ -300,7 +300,7 @@ Inject head and/or body HTML tags to Docusaurus generated HTML.
|
|||
|
||||
`injectHtmlTags` will be called both with the content loaded by the plugin.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
function injectHtmlTags(): {
|
||||
headTags?: HtmlTags;
|
||||
preBodyTags?: HtmlTags;
|
||||
|
|
@ -369,7 +369,7 @@ module.exports = function (context, options) {
|
|||
|
||||
## `getClientModules()` {#getClientModules}
|
||||
|
||||
Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.
|
||||
Returns an array of paths to the modules that are to be imported into the client bundle. These modules are imported globally before React even renders the initial UI.
|
||||
|
||||
As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Static methods are not part of the plugin instance—they are attached to the co
|
|||
|
||||
## `validateOptions({options, validate})` {#validateOptions}
|
||||
|
||||
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.
|
||||
Returns validated and normalized options for the plugin. This method is called before the plugin is initialized. You must return the options since they will be passed to the plugin during initialization.
|
||||
|
||||
### `options` {#options}
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ Return validated and normalized options for the plugin. This method is called be
|
|||
|
||||
### `validate` {#validate}
|
||||
|
||||
`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
|
||||
`validateOptions` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and options as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config.
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ Return validated and normalized configuration for the theme.
|
|||
|
||||
### `validate` {#validate-1}
|
||||
|
||||
`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
|
||||
`validateThemeConfig` is called with `validate` function which takes a **[Joi](https://www.npmjs.com/package/joi)** schema and `themeConfig` as the arguments, returns validated and normalized options. `validate` will automatically handle error and validation config.
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type EditUrlFunction = (params: {
|
||||
blogDirPath: string;
|
||||
blogPath: string;
|
||||
|
|
@ -191,9 +191,9 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Markdown Frontmatter {#markdown-frontmatter}
|
||||
## Markdown front matter {#markdown-front-matter}
|
||||
|
||||
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
|
||||
Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.
|
||||
|
||||
Accepted fields:
|
||||
|
||||
|
|
@ -201,7 +201,7 @@ Accepted fields:
|
|||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. |
|
||||
| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` front matter fields, even for single author blog posts. |
|
||||
| `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. |
|
||||
| `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
|
||||
| `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. |
|
||||
|
|
@ -220,7 +220,7 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type Tag = string | {label: string; permalink: string};
|
||||
|
||||
// An author key references an author from the global plugin authors.yml file
|
||||
|
|
@ -234,13 +234,13 @@ type Author = {
|
|||
image_url?: string;
|
||||
};
|
||||
|
||||
// The FrontMatter authors field allows various possible shapes
|
||||
// The front matter authors field allows various possible shapes
|
||||
type Authors = AuthorKey | Author | (AuthorKey | Author)[];
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
title: Welcome Docusaurus v2
|
||||
authors:
|
||||
|
|
@ -255,6 +255,7 @@ description: This is my first post on Docusaurus 2.
|
|||
image: https://i.imgur.com/mErPwqL.png
|
||||
hide_table_of_contents: false
|
||||
---
|
||||
|
||||
A Markdown blog post
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type EditUrlFunction = (params: {
|
||||
version: string;
|
||||
versionDocsDirPath: string;
|
||||
|
|
@ -236,9 +236,9 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Markdown Frontmatter {#markdown-frontmatter}
|
||||
## Markdown front matter {#markdown-front-matter}
|
||||
|
||||
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
|
||||
Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.
|
||||
|
||||
Accepted fields:
|
||||
|
||||
|
|
@ -252,7 +252,7 @@ Accepted fields:
|
|||
| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
|
||||
| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
|
||||
| `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
|
||||
| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. |
|
||||
| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
|
||||
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
|
||||
| `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
|
||||
| `toc_max_heading_level` | `number` | `3` | The max heading level shown in the table of contents. Must be between 2 and 6. |
|
||||
|
|
@ -268,13 +268,13 @@ Accepted fields:
|
|||
|
||||
</APITable>
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type Tag = string | {label: string; permalink: string};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
id: doc-markdown
|
||||
title: Docs Markdown Features
|
||||
|
|
@ -291,6 +291,7 @@ keywords:
|
|||
image: https://i.imgur.com/mErPwqL.png
|
||||
slug: /myDoc
|
||||
---
|
||||
|
||||
# Markdown Features
|
||||
|
||||
My Document Markdown content
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue