From a7e3102e9dd422552d18de26088e4d084707c830 Mon Sep 17 00:00:00 2001 From: Evan You Date: Fri, 3 Mar 2023 10:48:37 +0800 Subject: [PATCH] docs: cli reference --- docs/guide/getting-started.md | 50 ++++++++++++++++++----- docs/reference/cli.md | 75 ++++++++++++++++++++++++++++++++++- 2 files changed, 113 insertions(+), 12 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 90a3594e..0b5e5692 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -39,24 +39,32 @@ If using PNPM, you will notice a missing peer warning for `@docsearch/js`. This ::: -## Setup Wizard +### Setup Wizard -VitePress ships with a command line setup wizard that will help you scaffold a basic project. Start the wizard by running: +VitePress ships with a command line setup wizard that will help you scaffold a basic project. After installation, start the wizard by running: -```sh +::: code-group + +```sh [npm] $ npx vitepress init ``` -You should be greeted with the following: +```sh [pnpm] +$ pnpm exec vitepress init +``` + +::: + +You will be greeted with a few simple questions:

vitepress init screenshot

-If you are installing VitePress in an existing project alongside the source code, it is recommended to scaffold the site in a nested directory so that it is separate from the rest of the project. - ## File Structure +If you are building a standalone VitePress site, you can scaffold the site in your current directory (`./`). However, if you are installing VitePress in an existing project alongside other source code, it is recommended to scaffold the site in a nested directory (e.g. `./docs`) so that it is separate from the rest of the project. + Assuming you chose to scaffold the VitePress project in `./docs`, the generated file structure should look like this: ``` @@ -70,11 +78,15 @@ Assuming you chose to scaffold the VitePress project in `./docs`, the generated └─ package.json ``` -The `docs` directory is considered the **project root** of the VitePress site. The `.vitepress` directory contains the config file, dev server cache, build output, and optional theme customization code. +The `docs` directory is considered the **project root** of the VitePress site. The `.vitepress` directory is a reserved location for VitePress' config file, dev server cache, build output, and optional theme customization code. + +:::tip +By default, VitePress stores its dev server cache in `.vitepress/cache`, and the production build output in `.vitepress/dist`. If using Git, you should add them to your `.gitignore` file. These locations can also be [configured](/reference/site-config#outdir). +::: ### The Config File -The config file allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site: +The config file (`.vitepress/config.js`) allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site: ```js // .vitepress/config.js @@ -89,7 +101,7 @@ export default { } ``` -You can also configure the behavior of the theme via the `themeConfig` option. Consult the [Site Config Reference](/reference/site-config) for full details on all config options. +You can also configure the behavior of the theme via the `themeConfig` option. Consult the [Config Reference](/reference/site-config) for full details on all config options. ### Source Files @@ -97,7 +109,7 @@ Markdown files outside the `.vitepress` directory are considered **source files* VitePress uses **file-based routing**: each `.md` file is compiled into a corresponding `.html` file with the same path. For example, `index.md` will be compiled into `index.html`, and can be visited at the root path `/` of the resulting VitePress site. -We will discuss more about [Routing](./routing) in the next chapter. +VitePress also provides the ability to generate clean URLs, rewrite paths, and dynamically generate pages. These will be covered in the [Routing Guide](./routing). ## Up and Running @@ -123,16 +135,32 @@ The `docs:dev` script will start a local dev server with instant hot updates. Ru $ npm run docs:dev ``` +```sh [pnpm] +$ pnpm run docs:dev +``` + ```sh [yarn] $ yarn docs:dev ``` +::: + +Instead of npm scripts, you can also invoke VitePress directly with: + +::: code-group + +```sh [npm] +$ npx vitepress dev docs +``` + ```sh [pnpm] -$ pnpm run docs:dev +$ pnpm exec vitepress dev docs ``` ::: +More command line usage is documented in the [CLI Reference](/reference/cli). + The dev server should be running at `http://localhost:5173`. Visit the URL in your browser to see your new site in action! ## What's Next? diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 3f213d43..363e73b0 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1 +1,74 @@ -# CLI +# Command Line Interface + +## `vitepress dev` + +Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. + +### Usage + +```sh +# start in current directory, omitting `dev` +vitepress + +# start in sub directory +vitepress dev [root] +``` + +### Options + +| Option | Description | +| - | - | +| `--open [path]` | Open browser on startup (`boolean \| string`) | +| `--port ` | Specify port (`number`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--cors` | Enable CORS | +| `--strictPort` | Exit if specified port is already in use (`boolean`) | +| `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | + +## `vitepress build` + +Build the VitePress site for production. + +### Usage + +```sh +vitepress build [root] +``` + +### Options + +| Option | Description | +| - | - | +| `--mpa` (experimental) | Build in MPA mode without client-side hydration (`boolean`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--target ` | Transpile target (default: `"modules"`) (`string`) | +| `--outDir ` | Output directory (default: `.vitepress/dist`) (`string`) | +| `--minify [minifier]` | Enable/disable minification, or specify minifier to use (default: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) | +| `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | + +## `vitepress preview` + +Locally preview the production build. + +### Usage + +```sh +vitepress preview [root] +``` + +### Options + +| Option | Description | +| - | - | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--port ` | Specify port (`number`) | + +## `vitepress init` + +Start the [Setup Wizard](/guide/getting-started#setup-wizard) in current directory. + +### Usage + +```sh +vitepress init +```