mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-24 22:46:57 +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:
parent
3195e7feed
commit
73ee356949
56 changed files with 432 additions and 383 deletions
|
@ -10,16 +10,16 @@ Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
|
|||
```bash
|
||||
website # root directory of your site
|
||||
├── docs
|
||||
│ └── greeting.md
|
||||
│ └── greeting.md
|
||||
├── src
|
||||
│ └── pages
|
||||
│ └── pages
|
||||
├── docusaurus.config.js
|
||||
├── ...
|
||||
```
|
||||
|
||||
At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
id: greeting
|
||||
title: Hello
|
||||
|
@ -35,7 +35,7 @@ will show up on the table of contents on the upper right
|
|||
|
||||
So that your users will know what this page is all about without scrolling down or even without reading too much.
|
||||
|
||||
### Only h2 and h3 will be in the toc by default.
|
||||
### Only h2 and h3 will be in the TOC by default.
|
||||
|
||||
You can configure the TOC heading levels either per-document or in the theme configuration.
|
||||
|
||||
|
@ -69,9 +69,9 @@ will show up on the table of contents on the upper right
|
|||
|
||||
So that your users will know what this page is all about without scrolling down or even without reading too much.
|
||||
|
||||
<h3>Only h2 and h3 will be in the toc by default.</h3>
|
||||
<h3>Only h2 and h3 will be in the TOC by default.</h3>
|
||||
|
||||
You can configure the TOC heading levels either per-document or in the theme configuration.
|
||||
You can configure the TOC heading levels either per document or in the theme configuration.
|
||||
|
||||
The headers are well-spaced so that the hierarchy is clear.
|
||||
|
||||
|
@ -100,7 +100,7 @@ Read more about [importing partial pages](../markdown-features/markdown-features
|
|||
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels:
|
||||
|
||||
```yml "your-doc-page.md"
|
||||
```md "your-doc-page.md"
|
||||
---
|
||||
id: doc-with-tags
|
||||
title: A doc with tags
|
||||
|
|
|
@ -27,22 +27,24 @@ website # Root directory of your site
|
|||
└── hello.md
|
||||
```
|
||||
|
||||
However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
|
||||
However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
id: part1
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
id: part1
|
||||
slug: part1.html
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
|
@ -57,13 +59,14 @@ It is possible to use:
|
|||
|
||||
## Home page docs {#home-page-docs}
|
||||
|
||||
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter:
|
||||
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
id: my-home-doc
|
||||
slug: /
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
|
@ -83,7 +86,7 @@ example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-m
|
|||
...
|
||||
```
|
||||
|
||||
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root?
|
||||
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting them at the root?
|
||||
|
||||
Assume that you have the following in your configuration:
|
||||
|
||||
|
@ -126,15 +129,16 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
|
||||
Note that you **don't necessarily have to give up on using the blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
|
||||
|
||||
Don't forget to put some page at the root (`https://example.com/`) through adding the front matter:
|
||||
|
||||
```yml title="docs/intro.md"
|
||||
```md title="docs/intro.md"
|
||||
---
|
||||
# highlight-next-line
|
||||
slug: /
|
||||
---
|
||||
|
||||
This page will be the home page when users visit https://example.com/.
|
||||
```
|
||||
|
||||
|
|
|
@ -5,11 +5,11 @@ description: Docusaurus Markdown features that are specific to the docs plugin
|
|||
slug: /docs-markdown-features
|
||||
---
|
||||
|
||||
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional docs-specific Markdown features.
|
||||
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features.
|
||||
|
||||
## Markdown frontmatter {#markdown-frontmatter}
|
||||
## Markdown front matter {#markdown-front-matter}
|
||||
|
||||
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
|
||||
Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
|
||||
|
||||
## Referencing other documents {#referencing-other-documents}
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@ The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../
|
|||
|
||||
:::note
|
||||
|
||||
This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page.
|
||||
This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar.md#using-multiple-sidebars), you can do so within one plugin.
|
||||
|
||||
:::
|
||||
|
||||
|
@ -26,7 +26,7 @@ If you build a cross-platform mobile SDK, you may have 2 documentations:
|
|||
- Android SDK documentation (`v1.0`, `v1.1`)
|
||||
- iOS SDK documentation (`v1.0`, `v2.0`)
|
||||
|
||||
In such case, you can use a distinct docs plugin instance per mobile SDK documentation.
|
||||
In this case, you can use a distinct docs plugin instance per mobile SDK documentation.
|
||||
|
||||
:::caution
|
||||
|
||||
|
|
|
@ -14,7 +14,7 @@ Creating a sidebar is useful to:
|
|||
|
||||
- Group multiple **related documents**
|
||||
- **Display a sidebar** on each of those documents
|
||||
- Provide a **paginated navigation**, with next/previous button
|
||||
- Provide **paginated navigation**, with next/previous button
|
||||
|
||||
To use sidebars on your Docusaurus site:
|
||||
|
||||
|
@ -58,7 +58,7 @@ You can also define your sidebars explicitly.
|
|||
|
||||
A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type Sidebar =
|
||||
// Normal syntax
|
||||
| SidebarItem[]
|
||||
|
@ -108,7 +108,7 @@ This is a sidebars file that exports one sidebar, called `mySidebar`. It has thr
|
|||
|
||||
A sidebars file can contain [**multiple sidebar objects**](#using-multiple-sidebars), identified by their object keys.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type SidebarsFile = {
|
||||
[sidebarID: string]: Sidebar;
|
||||
};
|
||||
|
@ -235,7 +235,7 @@ Note how the two consecutive category shorthands are compressed into one object
|
|||
|
||||
## Understanding sidebar items {#understanding-sidebar-items}
|
||||
|
||||
We have introduced three types of item types in the above example: `doc`, `category`, and `link`, whose usage are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later.
|
||||
We have introduced three types of item types in the above example: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later.
|
||||
|
||||
- **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar
|
||||
- **[Link](#sidebar-item-link)**: link to any internal or external page
|
||||
|
@ -247,7 +247,7 @@ We have introduced three types of item types in the above example: `doc`, `categ
|
|||
|
||||
Use the `doc` type to link to a doc page and assign that doc to a sidebar:
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type SidebarItemDoc =
|
||||
// Normal syntax
|
||||
| {
|
||||
|
@ -283,7 +283,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has a higher precedence over the `label` key in the sidebar item.
|
||||
If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item.
|
||||
|
||||
:::note
|
||||
|
||||
|
@ -295,7 +295,7 @@ A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't
|
|||
|
||||
Use the `link` type to link to any page (internal or external) that is not a doc.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type SidebarItemLink = {
|
||||
type: 'link';
|
||||
label: string;
|
||||
|
@ -334,7 +334,7 @@ module.exports = {
|
|||
|
||||
Use the `category` type to create a hierarchy of sidebar items.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type SidebarItemCategory = {
|
||||
type: 'category';
|
||||
label: string; // Sidebar label text.
|
||||
|
@ -419,7 +419,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md).
|
||||
See it in action on the [i18n introduction page](../../i18n/i18n-introduction.md).
|
||||
|
||||
##### Generated index page {#generated-index-page}
|
||||
|
||||
|
@ -445,7 +445,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
See it in action in the [Docusaurus Guides pages](/docs/category/guides).
|
||||
See it in action on the [Docusaurus Guides page](/docs/category/guides).
|
||||
|
||||
:::tip
|
||||
|
||||
|
@ -504,7 +504,7 @@ The option in `sidebars.js` takes precedence over plugin configuration, so it is
|
|||
|
||||
#### Expanded categories by default {#expanded-categories-by-default}
|
||||
|
||||
Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`:
|
||||
Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
|
@ -551,7 +551,7 @@ When a category has `collapsed: true` but `collapsible: false` (either through `
|
|||
|
||||
Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category, and each file creates a doc link.
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
type SidebarItemAutogenerated = {
|
||||
type: 'autogenerated';
|
||||
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
|
||||
|
@ -576,7 +576,7 @@ module.exports = {
|
|||
An `autogenerated` item is converted by Docusaurus to a **sidebar slice** (also discussed in [category shorthands](#category-shorthand)): a list of items of type `doc` or `category`, so you can splice **multiple `autogenerated` items** from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
|
||||
|
||||
<details>
|
||||
<summary>A real world example</summary>
|
||||
<summary>A real-world example</summary>
|
||||
Consider this file structure:
|
||||
|
||||
```bash
|
||||
|
@ -736,11 +736,11 @@ Naming your introductory document `README.md` makes it show up when browsing the
|
|||
|
||||
#### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
|
||||
|
||||
For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
|
||||
For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
|
||||
|
||||
**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter.
|
||||
|
||||
```yaml title="docs/tutorials/tutorial-easy.md"
|
||||
```md title="docs/tutorials/tutorial-easy.md"
|
||||
---
|
||||
# highlight-start
|
||||
sidebar_position: 2
|
||||
|
@ -748,6 +748,7 @@ sidebar_label: Easy
|
|||
sidebar_class_name: green
|
||||
# highlight-end
|
||||
---
|
||||
|
||||
# Easy Tutorial
|
||||
|
||||
This is the easy tutorial!
|
||||
|
@ -775,7 +776,7 @@ This is the easy tutorial!
|
|||
</TabItem>
|
||||
<TabItem value="YAML">
|
||||
|
||||
```yaml title="docs/tutorials/_category_.yml"
|
||||
```yml title="docs/tutorials/_category_.yml"
|
||||
position: 2.5 # float position is supported
|
||||
label: 'Tutorial'
|
||||
collapsible: true # make the category collapsible
|
||||
|
@ -824,7 +825,7 @@ docs
|
|||
|
||||
To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**.
|
||||
|
||||
By default, Docusaurus will **remove the number prefix** from the doc id, title, label and URL paths.
|
||||
By default, Docusaurus will **remove the number prefix** from the doc id, title, label, and URL paths.
|
||||
|
||||
:::caution
|
||||
|
||||
|
@ -874,7 +875,7 @@ module.exports = {
|
|||
|
||||
**Re-use and enhance the default generator** instead of writing a generator from scratch: [the default generator we provide](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts) is 250 lines long.
|
||||
|
||||
**Add, update, filter, re-order** the sidebar items according to your use-case:
|
||||
**Add, update, filter, re-order** the sidebar items according to your use case:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
|
@ -967,7 +968,7 @@ module.exports = {
|
|||
|
||||
How does Docusaurus know which sidebar to display when browsing `commonDoc`? Answer: it doesn't, and we don't guarantee which sidebar it will pick. In this case, in order to remove the ambiguity, you can use the special `ref` sidebar item type.
|
||||
|
||||
The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link, but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored.
|
||||
The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored.
|
||||
|
||||
So you can turn the sidebars above into:
|
||||
|
||||
|
@ -1007,11 +1008,12 @@ module.exports = {
|
|||
|
||||
The pagination next link on "windows" points to "linux", but that doesn't make sense: you would want readers to proceed to "getting started" after installation. In this case, you can set the pagination manually:
|
||||
|
||||
```yml title="windows.md"
|
||||
```md title="windows.md"
|
||||
---
|
||||
# highlight-next-line
|
||||
pagination_next: getting-started
|
||||
---
|
||||
|
||||
# Installation on Windows
|
||||
```
|
||||
|
||||
|
@ -1035,7 +1037,7 @@ To pass in custom props to a swizzled sidebar item, add the optional `customProp
|
|||
|
||||
## Complex sidebars example {#complex-sidebars-example}
|
||||
|
||||
Real-world example from the Docusaurus site:
|
||||
A real-world example from the Docusaurus site:
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
|
@ -18,7 +18,7 @@ To better understand how versioning works and see if it suits your needs, you ca
|
|||
|
||||
## Directory structure {#directory-structure}
|
||||
|
||||
```shell
|
||||
```bash
|
||||
website
|
||||
├── sidebars.json # sidebar for the current docs version
|
||||
├── docs # docs directory for the current docs version
|
||||
|
@ -54,7 +54,7 @@ The table below explains how a versioned file maps to its version and the genera
|
|||
|
||||
The files in the `docs` directory belong to the `current` docs version.
|
||||
|
||||
By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle.
|
||||
By default, the `current` docs version is labeled as `Next` and hosted under `/docs/next/*`, but it is entirely configurable to fit your project's release lifecycle.
|
||||
|
||||
:::
|
||||
|
||||
|
@ -78,11 +78,11 @@ When tagging a new version, the document versioning mechanism will:
|
|||
### Creating new docs {#creating-new-docs}
|
||||
|
||||
1. Place the new file into the corresponding version folder.
|
||||
1. Include the reference for the new file into the corresponding sidebar file, according to version number.
|
||||
2. Include the reference to the new file in the corresponding sidebar file according to the version number.
|
||||
|
||||
**Current version docs**
|
||||
|
||||
```shell
|
||||
```bash
|
||||
# The new file.
|
||||
docs/new.md
|
||||
|
||||
|
@ -92,7 +92,7 @@ sidebar.js
|
|||
|
||||
**Older version docs**
|
||||
|
||||
```shell
|
||||
```bash
|
||||
# The new file.
|
||||
versioned_docs/version-1.0.0/new.md
|
||||
|
||||
|
@ -103,7 +103,7 @@ versioned_sidebars/version-1.0.0-sidebars.json
|
|||
### Linking docs {#linking-docs}
|
||||
|
||||
- Remember to include the `.md` extension.
|
||||
- Files will be linked to correct corresponding version.
|
||||
- Files will be linked to the correct corresponding version.
|
||||
- Relative paths work as well.
|
||||
|
||||
```md
|
||||
|
@ -156,9 +156,9 @@ There are different ways to manage versioning, but two very common patterns are:
|
|||
- You release v1, and start immediately working on v2 (including its docs)
|
||||
- You release v1, and will maintain it for some time before thinking about v2.
|
||||
|
||||
Docusaurus defaults work great for the first usecase.
|
||||
Docusaurus defaults work great for the first use case.
|
||||
|
||||
**For the 2nd usecase**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead:
|
||||
**For the 2nd use case**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead:
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -178,17 +178,23 @@ See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for mo
|
|||
|
||||
### Version your documentation only when needed {#version-your-documentation-only-when-needed}
|
||||
|
||||
For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
|
||||
For example, you are building documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
|
||||
|
||||
Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.
|
||||
|
||||
### Keep the number of versions small {#keep-the-number-of-versions-small}
|
||||
|
||||
As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation versions with the lowest being `22.X`. Keep it small 😊
|
||||
As a good rule of thumb, try to keep the number of your versions below 10. You will **very likely** to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `27.4`, and only maintains several latest documentation versions with the lowest being `25.X`. Keep it small 😊
|
||||
|
||||
:::tip archive older versions
|
||||
|
||||
If you deploy your site on a Jamstack provider (e.g. [Netlify](../../deployment.mdx)), the provider will save each production build as a snapshot under an immutable URL. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docusaurus website both use such pattern to keep the number of actively built versions low.
|
||||
|
||||
:::
|
||||
|
||||
### Use absolute import within the docs {#use-absolute-import-within-the-docs}
|
||||
|
||||
Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus, that points to the `website` directory. Example:
|
||||
Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus that points to the `website` directory. Example:
|
||||
|
||||
```diff
|
||||
- import Foo from '../src/components/Foo';
|
||||
|
@ -197,7 +203,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
|
|||
|
||||
### Global or versioned colocated assets {#global-or-versioned-colocated-assets}
|
||||
|
||||
You should decide if assets like images and files are per version or shared between versions
|
||||
You should decide if assets like images and files are per-version or shared between versions.
|
||||
|
||||
If your assets should be versioned, put them in the docs version, and use relative paths:
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue