mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-20 04:27:04 +02:00
chore: release v3.5.1 (#10385)
This commit is contained in:
Sébastien Lorber
GitHub
parent
9c5eb35e51
commit
bde4414614
142 changed files with 379 additions and 203 deletions
190
website/versioned_docs/version-3.5.1/cli.mdx
Normal file
190
website/versioned_docs/version-3.5.1/cli.mdx
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
---
|
||||
description: Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
|
||||
---
|
||||
|
||||
# CLI
|
||||
|
||||
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
|
||||
|
||||
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"
|
||||
{
|
||||
// ...
|
||||
"scripts": {
|
||||
"docusaurus": "docusaurus",
|
||||
"start": "docusaurus start",
|
||||
"build": "docusaurus build",
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"deploy": "docusaurus deploy",
|
||||
"clear": "docusaurus clear",
|
||||
"serve": "docusaurus serve",
|
||||
"write-translations": "docusaurus write-translations",
|
||||
"write-heading-ids": "docusaurus write-heading-ids"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Docusaurus CLI commands {#docusaurus-cli-commands}
|
||||
|
||||
Below is a list of Docusaurus CLI commands and their usages:
|
||||
|
||||
### `docusaurus start [siteDir]` {#docusaurus-start-sitedir}
|
||||
|
||||
Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
|
||||
|
||||
#### Options {#options}
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--port` | `3000` | Specifies the port of the dev server. |
|
||||
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
|
||||
| `--locale` | | Specify site locale to be used. |
|
||||
| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
|
||||
| `--no-open` | `false` | Do not open the page automatically in the browser. |
|
||||
| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
|
||||
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
|
||||
|
||||
:::info
|
||||
|
||||
Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.
|
||||
|
||||
:::
|
||||
|
||||
:::info Development over network
|
||||
|
||||
When forwarding port 3000 from a remote server or VM (e.g. GitHub Codespaces), you can run the dev server on `0.0.0.0` to make it listen on the local IP.
|
||||
|
||||
```bash npm2yarn
|
||||
npm run start -- --host 0.0.0.0
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Enabling HTTPS {#enabling-https}
|
||||
|
||||
There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example.
|
||||
|
||||
1. Run `mkcert localhost` to generate `localhost.pem` + `localhost-key.pem`
|
||||
|
||||
2. Run `mkcert -install` to install the cert in your trust store, and restart your browser
|
||||
|
||||
3. Start the app with Docusaurus HTTPS env variables:
|
||||
|
||||
```bash
|
||||
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
|
||||
```
|
||||
|
||||
4. Open `https://localhost:3000/`
|
||||
|
||||
### `docusaurus build [siteDir]` {#docusaurus-build-sitedir}
|
||||
|
||||
Compiles your site for production.
|
||||
|
||||
#### Options {#options-1}
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--dev` | | Builds the website in dev mode, including full React error messages. |
|
||||
| `--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. |
|
||||
| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--locale` | | Build the site in the specified locale. If not specified, all known locales are built. |
|
||||
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
|
||||
|
||||
:::info
|
||||
|
||||
For advanced minification of CSS bundle, we use the [advanced cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-advanced) (along with additional several PostCSS plugins) and [level 2 optimization of clean-css](https://github.com/jakubpawlowicz/clean-css#level-2-optimizations). If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable `USE_SIMPLE_CSS_MINIFIER=true` to minify CSS with the [default cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-default). **Please [fill out an issue](https://github.com/facebook/docusaurus/issues/new?labels=bug%2C+needs+triage&template=bug.md) if you experience CSS minification bugs.**
|
||||
|
||||
You can skip the HTML minification with the environment variable `SKIP_HTML_MINIFICATION=true`.
|
||||
|
||||
:::
|
||||
|
||||
### `docusaurus swizzle [themeName] [componentName] [siteDir]` {#docusaurus-swizzle}
|
||||
|
||||
[Swizzle](./swizzling.mdx) a theme component to customize it.
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle [themeName] [componentName] [siteDir]
|
||||
|
||||
# Example (leaving out the siteDir to indicate this directory)
|
||||
npm run swizzle @docusaurus/theme-classic Footer -- --eject
|
||||
```
|
||||
|
||||
The swizzle CLI is interactive and will guide you through the whole [swizzle process](./swizzling.mdx).
|
||||
|
||||
#### Options {#options-swizzle}
|
||||
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `themeName` | The name of the theme to swizzle from. |
|
||||
| `componentName` | The name of the theme component to swizzle. |
|
||||
| `--list` | Display components available for swizzling |
|
||||
| `--eject` | [Eject](./swizzling.mdx#ejecting) the theme component |
|
||||
| `--wrap` | [Wrap](./swizzling.mdx#wrapping) the theme component |
|
||||
| `--danger` | Allow immediate swizzling of unsafe components |
|
||||
| `--typescript` | Swizzle the TypeScript variant component |
|
||||
| `--config` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
|
||||
:::warning
|
||||
|
||||
Unsafe components have a higher risk of breaking changes due to internal refactorings.
|
||||
|
||||
:::
|
||||
|
||||
### `docusaurus deploy [siteDir]` {#docusaurus-deploy-sitedir}
|
||||
|
||||
Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details.
|
||||
|
||||
#### Options {#options-3}
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--locale` | | Deploy the site in the specified locale. If not specified, all known locales are deployed. |
|
||||
| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
|
||||
| `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. |
|
||||
| `--target-dir` | `.` | Path to the target directory to deploy to. |
|
||||
| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
|
||||
### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
|
||||
|
||||
Serve your built website locally.
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--port` | `3000` | Use specified port |
|
||||
| `--dir` | `build` | The full path for the output directory, relative to the current workspace |
|
||||
| `--build` | `false` | Build website before serving |
|
||||
| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
|
||||
| `--no-open` | `false` locally, `true` in CI | Do not open a browser window to the server location. |
|
||||
|
||||
### `docusaurus clear [siteDir]` {#docusaurus-clear-sitedir}
|
||||
|
||||
Clear a Docusaurus site's generated assets, caches, build artifacts.
|
||||
|
||||
We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.
|
||||
|
||||
### `docusaurus write-translations [siteDir]` {#docusaurus-write-translations-sitedir}
|
||||
|
||||
Write the JSON translation files that you will have to translate.
|
||||
|
||||
By default, the files are written in `website/i18n/<defaultLocale>/...`.
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--locale` | `<defaultLocale>` | Define which locale folder you want to write translations the JSON files in |
|
||||
| `--override` | `false` | Override existing translation messages |
|
||||
| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
|
||||
| `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings |
|
||||
|
||||
### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir}
|
||||
|
||||
Add [explicit heading IDs](./guides/markdown-features/markdown-features-toc.mdx#heading-ids) to the Markdown documents of your site.
|
||||
|
||||
| Name | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `files` | All MD files used by plugins | The files that you want heading IDs to be written to. |
|
||||
| `--maintain-case` | `false` | Keep the headings' casing, otherwise make all lowercase. |
|
||||
| `--overwrite` | `false` | Overwrite existing heading IDs. |
|
||||
Loading…
Add table
Add a link
Reference in a new issue