3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-01 02:12:36 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): improve grammar (#2606)

Browse source 
Signed-off-by: Reece Dunham <me@rdil.rocks>
This commit is contained in:
Reece Dunham 2020-04-14 11:26:55 -04:00 • committed by GitHub
parent 6a2fdbe3ca
commit a7b802f31a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 36 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

39
website/docs/cli.md
View file

@ -5,7 +5,7 @@ title: CLI
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
Once your website is generated, your website package will contain the Docusaurus scripts that you may invoke with your package manager:
Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:
```json title="package.json"
{
@ -38,11 +38,11 @@ $ npm install --global docusaurus
### `docusaurus start`
Builds and serves the static site with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
**options**
#### Options
| Options | Default | Description |
| Name | Default | Description |
| --- | --- | --- |
| `--port` | `3000` | Specifies the port of the dev server |
| `--host` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use `--host 0.0.0.0` |
@ -51,7 +51,7 @@ Builds and serves the static site with [Webpack Dev Server](https://webpack.js.o
:::important
Please note that some functionality (for example, anchor links) will not work in dev server. When building the website, all the functionality will work as expected.
Please note that some functionality (for example, anchor links) will not work in development. Don't freak out though, the functionality will work as expected in production.
:::
@ -59,11 +59,11 @@ Please note that some functionality (for example, anchor links) will not work in
Compiles your site for production.
**options**
#### Options
| Options | Default | Description |
| Name | Default | Description |
| --- | --- | --- |
| `--bundle-analyzer` | | Analyze your bundle with [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
| `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
@ -71,35 +71,38 @@ Compiles your site for production.
:::caution
We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
:::
Swizzle any Docusaurus Theme components with your own component with `docusaurus swizzle`.
Change any Docusaurus theme components to your liking with `docusaurus swizzle`.
```shell
docusaurus swizzle <themeName> [componentName] [siteDir]
```
**params**
Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
- `themeName`: name of the theme you are using
- `swizzleComponent`: name of the component to be swizzled
#### Options
Running the above command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
| Name | Description |
| ------------------ | ------------------------------------- |
| `themeName` | The name of the theme you are using. |
| `swizzleComponent` | The name of the component to swizzle. |
To unswizzle a component, simply delete the files of the swizzled component.
<!-- TODO a separate section for swizzle tutorial -->
<!--
TODO a separate section for swizzle tutorial.
To learn more about swizzling, check [here](#).
-->
### `docusaurus deploy`
Deploys your site with [GitHub Pages](https://pages.github.com/).
**options**
#### Options
| Options | Default | Description |
| Name | Default | Description |
| --- | --- | --- |
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |

16
website/docs/configuration.md
View file

@ -3,13 +3,13 @@ id: configuration
title: Configuration
---
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site.
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site.
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize fields.
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site.
## What goes into `docusaurus.config.js`?
## What goes into a `docusaurus.config.js`?
You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` at root that includes the necessary data for the initial site.
You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options.
However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.
@ -20,7 +20,7 @@ The high-level overview of Docusaurus configuration can be categorized into:
- [Theme, Plugin, and Preset Configurations](#theme-plugin-and-preset-configurations)
- [Custom Configurations](#custom-configurations)
For exact reference to each of the configurable fields, you may refer to [**docusaurus.config.js API reference**](docusaurus.config.js.md).
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](docusaurus.config.js.md).
### Site metadata
@ -30,13 +30,13 @@ They are used in a number of places such as your site's title and headings, brow
### Deployment configurations
Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with Docusaurus' `deploy` command.
Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command.
It is recommended to check the [deployment docs](deployment.md) for more information.
### Theme, plugin, and preset configurations
List the installed [themes](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
```js title="docusaurus.config.js"
module.exports = {
@ -105,7 +105,7 @@ For further help configuring themes, plugins, and presets, see [Using Themes](us
### Custom configurations
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`.
Example:

1
website/docs/markdown-features.mdx
View file

@ -121,7 +121,6 @@ image: https://i.imgur.com/mErPwqL.png
---
```
## Referencing other documents
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).

18
website/docs/versioning.md
View file

@ -3,15 +3,11 @@ id: versioning
title: Versioning
---
You can use the version script to cut a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
:::caution
:::caution Think about it before starting to version your documentation - it can become difficult for contributors to help improve it! :::
Consider well before starting to version your documentation.
:::
Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
To better understand how versioning works and see if it suits your needs, you can read on below.
@ -61,8 +57,8 @@ npm run docusaurus docs:version 1.1.0
When tagging a new version, the document versioning mechanism will:
- Copy the full `docs/` folder contents into a new `versioned_docs/version-<version>/` folder.
- Create a versioned sidebars file based from your current [sidebar](sidebar.md) configuration (if it exists). Saved it as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number into `versions.json`.
- Create a versioned sidebars file based from your current [sidebar](sidebar.md) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`.
## Files
@ -109,13 +105,13 @@ Each directory in `versioned_docs/` will represent a documentation version.
### Updating an existing version
You can update multiple docs versions at the same time. Because each directory in `versioned_docs/` represents specific routes when published.
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
1. Edit any file.
1. Commit and push changes.
1. It will be published to the version.
**Example:** When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
### Deleting an existing version