docs: update bundler and theme guide, improve getting-started guide

vuepress · Dec 28, 2023 · 381d6de · 381d6de
1 parent 1c9df72
commit 381d6de
Show file tree

Hide file tree

Showing 18 changed files with 378 additions and 190 deletions.
diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md
@@ -1,67 +1,63 @@
 # Bundler
 
-VuePress has been using [Webpack](https://webpack.js.org/) as the bundler to dev and build sites. Since VuePress v2, other bundlers are also supported, and now we are using [Vite](https://vitejs.dev/) as the default bundler. Of course, you can still choose to use Webpack.
+VuePress supports using [Webpack](https://webpack.js.org/) or [Vite](https://vitejs.dev/) to dev and build sites. You can choose which bundler to use according to your preference, and no extra configuration is required.
 
-## Choose a Bundler
+## Install a Bundler
 
-When using the [vuepress](https://www.npmjs.com/package/vuepress) package, Vite bundler is installed and used automatically.
-
-If you want to use Webpack bundler instead, you can remove it and install the [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) package instead:
+When installing the [vuepress](https://www.npmjs.com/package/vuepress) package, no bundlers will be installed. You need to choose a bundler to install.
 
 <CodeGroup>
-  <CodeGroupItem title="PNPM" active>
+  <CodeGroupItem title="pnpm" active>
 
 ```bash
-pnpm remove vuepress
-pnpm add -D vuepress-webpack@next
+# install vite bundler
+pnpm add -D vuepress@next @vuepress/bundler-vite@next
+# install webpack bundler
+pnpm add -D vuepress@next @vuepress/bundler-webpack@next
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="YARN">
+  <CodeGroupItem title="yarn">
 
 ```bash
-yarn remove vuepress
-yarn add -D vuepress-webpack@next
+# install vite bundler
+yarn add -D vuepress@next @vuepress/bundler-vite@next
+# install webpack bundler
+yarn add -D vuepress@next @vuepress/bundler-webpack@next
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="NPM">
+  <CodeGroupItem title="npm">
 
 ```bash
-npm uninstall vuepress
-npm install -D vuepress-webpack@next
+# install vite bundler
+npm install -D vuepress@next @vuepress/bundler-vite@next
+# install webpack bundler
+npm install -D vuepress@next @vuepress/bundler-webpack@next
 ```
 
   </CodeGroupItem>
 </CodeGroup>
 
-::: tip
-In fact, the [vuepress](https://www.npmjs.com/package/vuepress) package is just a wrapper of the [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package.
-:::
-
-## Configure Bundler
+## Use a Bundler
 
 Generally, you could use a bundler without extra configuration, because we have already configured them properly to work with VuePress.
 
-You can configure bundler for advanced usage via the [bundler](../reference/config.md#bundler) option:
+You can use a bundler via the [bundler](../reference/config.md#bundler) option:
 
 ```ts
-import { viteBundler } from 'vuepress'
-// import { webpackBundler } from 'vuepress-webpack'
+import { viteBundler } from '@vuepress/bundler-vite'
+// import { webpackBundler } from '@vuepress/bundler-webpack'
 
 export default {
-  bundler: viteBundler({
-    vuePluginOptions: {
-      template: {
-        compilerOptions: {
-          isCustomElement: (tag) => tag === 'center',
-        },
-      },
-    },
-  }),
+  bundler: viteBundler(),
+  // bundler: webpackBundler(),
 }
 ```
 
-You can refer to [Bundlers > Vite](../reference/bundler/vite.md) and [Bundlers > Webpack](../reference/bundler/webpack.md) to check out all options of the corresponding bundler.
+When you need to customize the bundler, you can set the corresponding options:
+
+- [Bundlers > Vite](../reference/bundler/vite.md)
+- [Bundlers > Webpack](../reference/bundler/webpack.md)
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -2,17 +2,6 @@
 
 ## Config File
 
-Without any configuration, the VuePress site is pretty minimal. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed. Your project structure is probably like this:
-
-```
-├─ docs
-│  ├─ .vuepress
-│  │  └─ config.js
-│  └─ README.md
-├─ .gitignore
-└─ package.json
-```
-
 The essential file for configuring a VuePress site is `.vuepress/config.js`, while TypeScript config file is also supported. You can use `.vuepress/config.ts` instead to get better types hint for VuePress config.
 
 To be more specific, we have a convention for config file paths (in order of precedence):
@@ -29,15 +18,20 @@ To be more specific, we have a convention for config file paths (in order of pre
 You can also specify the config file via `--config` option of [CLI](../reference/cli.md):
 
 ```sh
-vuepress dev docs --config my-config.js
+vuepress dev docs --config my-config.ts
 ```
 
 A basic config file looks like this:
 
 ```ts
+import { viteBundler } from '@vuepress/bundler-vite'
+import { defaultTheme } from '@vuepress/theme-default'
 import { defineUserConfig } from 'vuepress'
 
 export default defineUserConfig({
+  bundler: viteBundler(),
+  theme: defaultTheme(),
+
   lang: 'en-US',
   title: 'Hello VuePress',
   description: 'Just playing around',

diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -4,7 +4,13 @@
 VuePress v2 is currently in RC (Release Candidate) stage. It's ready to be used for building your site, but the config and API are not stable enough, which is possibly to have minor breaking changes. So make sure to read the [changelog](https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md) carefully each time you upgrade a RC version.
 :::
 
-## Prerequisites
+## Try It Online
+
+You can try VuePress directly in your browser on [StackBlitz](https://stackblitz.com/fork/vuepress).
+
+## Installation
+
+### Prerequisites
 
 - [Node.js v18.16.0+](https://nodejs.org/)
 - Package manager like [pnpm](https://pnpm.io), [yarn](https://classic.yarnpkg.com/en/), [npm](https://www.npmjs.com), etc.
@@ -16,21 +22,27 @@ VuePress v2 is currently in RC (Release Candidate) stage. It's ready to be used
 
 :::
 
-## Manual Installation
+### Project Setup
+
+#### Setup via CLI
 
-This section will help you build a basic VuePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
+TODO
 
-- **Step 1**: Create and change into a new directory
+#### Setup Manually
+
+This section will help you build a basic VuePress documentation site from ground up.
+
+- Create and change into a new directory
 
 ```bash
 mkdir vuepress-starter
 cd vuepress-starter
 ```
 
-- **Step 2**: Initialize your project
+- Initialize your project
 
 <CodeGroup>
-  <CodeGroupItem title="PNPM" active>
+  <CodeGroupItem title="pnpm" active>
 
 ```bash
 git init
@@ -39,7 +51,7 @@ pnpm init
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="YARN">
+  <CodeGroupItem title="yarn">
 
 ```bash
 git init
@@ -48,7 +60,7 @@ yarn init
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="NPM">
+  <CodeGroupItem title="npm">
 
 ```bash
 git init
@@ -58,35 +70,103 @@ npm init
   </CodeGroupItem>
 </CodeGroup>
 
-- **Step 3**: Install VuePress locally
+- Install VuePress
 
 <CodeGroup>
-  <CodeGroupItem title="PNPM" active>
+  <CodeGroupItem title="pnpm" active>
 
 ```bash
+# install vuepress and required peer dependencies
 pnpm add -D vuepress@next @vuepress/client@next vue
+# install bundler and theme
+pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="YARN">
+  <CodeGroupItem title="yarn">
 
 ```bash
+# install vuepress
 yarn add -D vuepress@next
+# install bundler and theme
+yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="NPM">
+  <CodeGroupItem title="npm">
 
 ```bash
+# install vuepress
 npm install -D vuepress@next
+# install bundler and theme
+npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next
 ```
 
   </CodeGroupItem>
 </CodeGroup>
 
-- **Step 4**: Add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`
+- Create `docs` directory and `docs/.vuepress` directory
+
+```bash
+mkdir docs
+mkdir docs/.vuepress
+```
+
+- Create the VuePress config file `docs/.vuepress/config.js`
+
+```ts
+import { viteBundler } from '@vuepress/bundler-vite'
+import { defaultTheme } from '@vuepress/theme-default'
+import { defineUserConfig } from 'vuepress'
+
+export default defineUserConfig({
+  bundler: viteBundler(),
+  theme: defaultTheme(),
+})
+```
+
+- Create your first document
+
+```bash
+echo '# Hello VuePress' > docs/README.md
+```
+
+## Directory Structure
+
+After the setup, the minimal structure of your project should look like this:
+
+```
+├─ docs
+│  ├─ .vuepress
+│  │  └─ config.js
+│  └─ README.md
+└─ package.json
+```
+
+The `docs` directory is where you put your markdown files, and it will be used as the source directory of VuePress.
+
+The `docs/.vuepress` directory, i.e. the `.vuepress` directory in the source directory, is where all VuePress-specific files will be placed. Currently there is only one config file in it. By default, the temp, cache and output directory will also be generated inside this directory. It is suggested to add them to your `.gitignore` file.
+
+::: details Example `.gitignore` file
+
+```
+# VuePress default temp directory
+.vuepress/.temp
+# VuePress default cache directory
+.vuepress/.cache
+# VuePress default build output directory
+.vuepress/dist
+```
+
+:::
+
+## Work with VuePress
+
+### Start Dev Server
+
+You can add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`:
 
 ```json
 {
@@ -97,49 +177,70 @@ npm install -D vuepress@next
 }
 ```
 
-- **Step 5**: Add the default temp and cache directory to `.gitignore` file
+Then, run `docs:dev` script to start the dev server:
+
+<CodeGroup>
+  <CodeGroupItem title="pnpm" active>
 
 ```bash
-echo 'node_modules' >> .gitignore
-echo '.temp' >> .gitignore
-echo '.cache' >> .gitignore
+pnpm docs:dev
 ```
 
-- **Step 6**: Create your first document
+  </CodeGroupItem>
+
+  <CodeGroupItem title="yarn">
 
 ```bash
-mkdir docs
-echo '# Hello VuePress' > docs/README.md
+yarn docs:dev
 ```
 
-- **Step 7**: Serve the documentation site in the local server
+  </CodeGroupItem>
+
+  <CodeGroupItem title="npm">
+
+```bash
+npm run docs:dev
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+VuePress will start a hot-reloading development server at [http://localhost:8080](http://localhost:8080). When you modify your markdown files, the content in the browser will be auto updated.
+
+### Build Your Site
+
+To build your site, run `docs:build` script:
 
 <CodeGroup>
-  <CodeGroupItem title="PNPM" active>
+  <CodeGroupItem title="pnpm" active>
 
 ```bash
-pnpm docs:dev
+pnpm docs:build
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="YARN">
+  <CodeGroupItem title="yarn">
 
 ```bash
-yarn docs:dev
+yarn docs:build
 ```
 
   </CodeGroupItem>
 
-  <CodeGroupItem title="NPM">
+  <CodeGroupItem title="npm">
 
 ```bash
-npm run docs:dev
+npm run docs:build
 ```
 
   </CodeGroupItem>
 </CodeGroup>
 
-VuePress will start a hot-reloading development server at [http://localhost:8080](http://localhost:8080). When you modify your markdown files, the content in the browser will be auto updated.
+You will see the generated static files in the `docs/.vuepress/dist` directory. You can check out [deployment](./deployment.md) for how to deploy them.
+
+## Learn More about VuePress
+
+By now, you should have a basic but functional VuePress site. But you may still need to read the subsequent guide to learn more about VuePress.
 
-By now, you should have a basic but functional VuePress documentation site. Next, learn about the basics of [configuration](./configuration.md) in VuePress.
+Next step, learn more about the [configuration](./configuration.md).