mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 07:37:19 +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
|
|
@ -20,7 +20,7 @@ Let's imagine the following file structure:
|
|||
|
||||
## Images {#images}
|
||||
|
||||
You can display images in three different ways: Markdown syntax, JSX require or ES imports syntax.
|
||||
You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax.
|
||||
|
||||
Display images using simple Markdown syntax:
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal
|
|||
|
||||
## Files {#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
|
||||
|
|
@ -95,7 +95,7 @@ import DocusaurusSvg from '@site/static/img/docusaurus.svg';
|
|||
|
||||
<DocusaurusSvg />
|
||||
|
||||
This can be useful, if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.
|
||||
This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.
|
||||
|
||||
```jsx
|
||||
import DocusaurusSvg from './docusaurus.svg';
|
||||
|
|
@ -154,5 +154,5 @@ If a Markdown link or image has an absolute path, the path will be seen as a fil
|
|||
|
||||
Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require` call instead of staying as a URL. This is desirable in two regards:
|
||||
|
||||
1. You don't have to worry about base URL, which Docusaurus will take care of when serving the asset;
|
||||
1. You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset;
|
||||
2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Code blocks within documentation are super-powered 💪.
|
|||
|
||||
## Code title {#code-title}
|
||||
|
||||
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 a `title` key after the language (leave a space between them).
|
||||
|
||||
```jsx title="/src/components/HelloCodeTitle.js"
|
||||
function HelloCodeTitle(props) {
|
||||
|
|
@ -25,7 +25,7 @@ function HelloCodeTitle(props) {
|
|||
|
||||
## Syntax highlighting {#syntax-highlighting}
|
||||
|
||||
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
|
||||
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX.
|
||||
|
||||
```jsx
|
||||
console.log('Every repo must come with a mascot.');
|
||||
|
|
@ -65,9 +65,9 @@ Some popular languages like Java, C#, or PHP are not enabled by default.
|
|||
|
||||
:::
|
||||
|
||||
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages.
|
||||
To add syntax highlighting for any of the other [Prism-supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages.
|
||||
|
||||
For example, if you want to add highlighting for the `powershell` language:
|
||||
For example, if you want to add highlighting for the PowerShell language:
|
||||
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
@ -148,7 +148,7 @@ html[data-theme='dark'] .docusaurus-highlight-code-line {
|
|||
}
|
||||
```
|
||||
|
||||
### Multiple line highlighting {#multiple-line-highlighting}
|
||||
### Multiple-line highlighting {#multiple-line-highlighting}
|
||||
|
||||
To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
|
||||
|
||||
|
|
@ -365,7 +365,7 @@ function MyPlayground(props) {
|
|||
|
||||
## Using JSX markup in code blocks
|
||||
|
||||
Code blocks in Markdown always preserves its content as plain text, meaning you can't do something like:
|
||||
Code block in Markdown always preserves its content as plain text, meaning you can't do something like:
|
||||
|
||||
```ts
|
||||
type EditUrlFunction = (params: {
|
||||
|
|
@ -407,11 +407,11 @@ Syntax highlighting only works on plain strings. Docusaurus will not attempt to
|
|||
|
||||
## Multi-language support code blocks {#multi-language-support-code-blocks}
|
||||
|
||||
With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.
|
||||
With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switch between them using a tabs component.
|
||||
|
||||
Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.
|
||||
|
||||
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.
|
||||
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 are **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.
|
||||
|
||||
````jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ My text
|
|||
|
||||
This `<head>` declaration has been added to the current Markdown doc, as a demo.
|
||||
|
||||
Open your browser DevTools and check how this page's metadata have been affected.
|
||||
Open your browser DevTools and check how this page's metadata has been affected.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -17,11 +17,11 @@ You can use regular Markdown headings.
|
|||
#### Level 4 title
|
||||
```
|
||||
|
||||
Markdown headings appear as a table-of-contents entry.
|
||||
Markdown headings appear as a table of contents entry.
|
||||
|
||||
## Heading ids {#heading-ids}
|
||||
|
||||
Each heading has an id that can be automatically generated, or explicitly specified.
|
||||
Each heading has an id that can be automatically generated or explicitly specified.
|
||||
|
||||
Heading ids allow you to link to a specific document heading in Markdown or JSX:
|
||||
|
||||
|
|
@ -35,9 +35,7 @@ Heading ids allow you to link to a specific document heading in Markdown or JSX:
|
|||
|
||||
### Generated ids {#generated-ids}
|
||||
|
||||
By default, Docusaurus will generate heading ids for you, based on the heading text.
|
||||
|
||||
`### Hello World` will have id `hello-world`.
|
||||
By default, Docusaurus will generate heading ids for you, based on the heading text. For example, `### Hello World` will have id `hello-world`.
|
||||
|
||||
Generated ids have **some limits**:
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ But it is also possible to display an inline table of contents directly inside a
|
|||
|
||||
## Full table of contents {#full-table-of-contents}
|
||||
|
||||
The `toc` variable is available in any MDX document, and contains all the headings of a MDX document.
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document.
|
||||
|
||||
By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel`.
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ import TOCInline from '@theme/TOCInline';
|
|||
|
||||
:::caution
|
||||
|
||||
The underlying content is just an example to have more table-of-contents items available in current page.
|
||||
Below is just some dummy content to have more table of contents items available on the current page.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
|
|||
|
||||
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
|
||||
|
||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||
|
||||
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example.
|
||||
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
|
||||
|
||||
:::important
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ The [standard Markdown syntax](https://daringfireball.net/projects/markdown/synt
|
|||
```md
|
||||
### My Doc Section
|
||||
|
||||
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
||||
Hello world message with some **bold** text, some _italic_ text, and a [link](/)
|
||||
|
||||
|
||||
```
|
||||
|
|
@ -53,10 +53,14 @@ Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
|||
Markdown quotes are beautifully styled:
|
||||
|
||||
```md
|
||||
> This is a quote
|
||||
> Easy to maintain open source documentation websites.
|
||||
>
|
||||
> — Docusaurus
|
||||
```
|
||||
|
||||
> This is a quote
|
||||
> Easy to maintain open source documentation websites.
|
||||
>
|
||||
> — Docusaurus
|
||||
|
||||
## Details
|
||||
|
||||
|
|
|
|||
|
|
@ -8,13 +8,13 @@ slug: /markdown-features/plugins
|
|||
Sometimes, you may want to extend or tweak your Markdown syntax. For example:
|
||||
|
||||
- How do I embed youtube videos using the image syntax (``)?
|
||||
- How do I style links that are on its own line differently, e.g., like a social card?
|
||||
- How do I style links that are on their own lines differently, e.g., as a social card?
|
||||
- How do I make every page start with a copyright notice?
|
||||
|
||||
And the answer is: create an MDX plugin! MDX has a built-in [plugin system](https://mdxjs.com/advanced/plugins/) that can be used to customize how the Markdown files will be parsed and transformed to JSX. There are three typical use-cases of MDX plugins:
|
||||
|
||||
- Using existing [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) or [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins);
|
||||
- Creating remark/rehype plugins to tranform the elements generated by existing MDX syntax;
|
||||
- Creating remark/rehype plugins to transform the elements generated by existing MDX syntax;
|
||||
- Creating remark/rehype plugins to introduce new syntaxes to MDX.
|
||||
|
||||
If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms:
|
||||
|
|
@ -24,7 +24,7 @@ If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-md
|
|||
|
||||
:::tip
|
||||
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project. The [admonition](./markdown-features-admonitions.mdx) syntax that we offer is also generated by a [Remark plugin](https://github.com/elviswolcott/remark-admonitions), and you could do the same for your own use-case.
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project. The [admonition](./markdown-features-admonitions.mdx) syntax that we offer is also generated by a [Remark plugin](https://github.com/elviswolcott/remark-admonitions), and you could do the same for your own use case.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ These are all typical use-cases of Remark plugins, which can also be a source of
|
|||
|
||||
## Installing plugins {#installing-plugins}
|
||||
|
||||
An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as example.
|
||||
An MDX plugin is usually an npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as an example.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save remark-math@3 rehype-katex@4
|
||||
|
|
@ -56,9 +56,9 @@ There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules
|
|||
<details>
|
||||
<summary>How are <code>remark-math</code> and <code>rehype-katex</code> different?</summary>
|
||||
|
||||
In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transforms that to the JSX `<span class="math math-inline">...</span>` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin.
|
||||
In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transform that to the JSX `<span class="math math-inline">...</span>` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin.
|
||||
|
||||
Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class, and uses $\KaTeX$ to parse and render the content to actual HTML.
|
||||
Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class and uses $\KaTeX$ to parse and render the content to actual HTML.
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -112,7 +112,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
You should check your plugin's documentation for options it supports.
|
||||
You should check your plugin's documentation for the options it supports.
|
||||
|
||||
## Creating new rehype/remark plugins
|
||||
|
||||
|
|
@ -124,7 +124,7 @@ The writeup below is **not** meant to be a comprehensive guide to creating a plu
|
|||
|
||||
:::
|
||||
|
||||
For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate NPM package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` which operates on the AST.
|
||||
For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate NPM package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` that operates on the AST.
|
||||
|
||||
```js "src/remark/section-prefix.js"
|
||||
const visit = require('unist-util-visit');
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Docusaurus has built-in support for [MDX v1](https://mdxjs.com/), which allows y
|
|||
|
||||
:::note
|
||||
|
||||
While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax.
|
||||
While Docusaurus parses both `.md` and `.mdx` files using MDX, some of the syntaxes are treated slightly differently by third-party tools. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -86,7 +86,7 @@ Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore,
|
|||
|
||||
## Importing code snippets {#importing-code-snippets}
|
||||
|
||||
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, first you need to install it in your project:
|
||||
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, you first need to install it in your project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save raw-loader
|
||||
|
|
@ -116,7 +116,7 @@ import MyComponentSource from '!!raw-loader!@site/src/pages/examples/_myComponen
|
|||
<br />
|
||||
```
|
||||
|
||||
You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock:
|
||||
You can also pass `title` prop to `CodeBlock` component in order for it to appear as header above your code block:
|
||||
|
||||
```jsx
|
||||
<CodeBlock className="language-jsx" title="/src/myComponent">
|
||||
|
|
@ -132,7 +132,7 @@ You have to use `<CodeBlock>` rather than the Markdown triple-backtick ` ``` `,
|
|||
|
||||
:::warning
|
||||
|
||||
This feature is experimental and might be subject to API breaking changes in the future.
|
||||
This feature is experimental and might be subject to breaking API changes in the future.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -164,11 +164,11 @@ import PartialExample from './_markdown-partial-example.mdx';
|
|||
<br />
|
||||
```
|
||||
|
||||
This way, you can reuse contents among multiple pages and avoid duplicating materials.
|
||||
This way, you can reuse content among multiple pages and avoid duplicating materials.
|
||||
|
||||
:::caution
|
||||
|
||||
The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
|
||||
The table of contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -132,11 +132,11 @@ It is possible to only render the default tab with `<Tabs lazy />`.
|
|||
|
||||
The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default.
|
||||
|
||||
Docusaurus will throw an error if a `defaultValue` is provided for the `Tabs` but it refers to an non-existing value. If you want none of the tabs to be shown by default, use `defaultValue={null}`.
|
||||
Docusaurus will throw an error if a `defaultValue` is provided for the `Tabs` but it refers to a non-existing value. If you want none of the tabs to be shown by default, use `defaultValue={null}`.
|
||||
|
||||
## Syncing tab choices {#syncing-tab-choices}
|
||||
|
||||
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that `groupID` are globally-namespaced.
|
||||
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to change all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that group IDs are globally namespaced.
|
||||
|
||||
```jsx
|
||||
// highlight-next-line
|
||||
|
|
@ -167,7 +167,7 @@ You may want choices of the same kind of tabs to sync with each other. For examp
|
|||
<br/>
|
||||
```
|
||||
|
||||
For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.
|
||||
For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group is chosen a value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups don't change.
|
||||
|
||||
```jsx
|
||||
<Tabs groupId="operating-systems">
|
||||
|
|
@ -195,7 +195,7 @@ For all tab groups that have the same `groupId`, the possible values do not need
|
|||
|
||||
---
|
||||
|
||||
Tab choices with different `groupId`s will not interfere with each other:
|
||||
Tab choices with different group IDs will not interfere with each other:
|
||||
|
||||
```jsx
|
||||
// highlight-next-line
|
||||
|
|
@ -227,7 +227,7 @@ Tab choices with different `groupId`s will not interfere with each other:
|
|||
|
||||
## Customizing tabs {#customizing-tabs}
|
||||
|
||||
You might want to customize the appearance of certain set of tabs. To do that you can pass the string in `className` prop and the specified CSS class will be added to the `Tabs` component:
|
||||
You might want to customize the appearance of a certain set of tabs. You can pass the string in `className` prop, and the specified CSS class will be added to the `Tabs` component:
|
||||
|
||||
```jsx
|
||||
// highlight-next-line
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue