diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md index 1a8640dc..744779f0 100644 --- 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. - + ```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 ``` - + ```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 ``` - + ```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 ``` -::: 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 index f07eed61..3231a19d 100644 --- 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 index 944de1e5..f697bbbd 100644 --- 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 - + ```bash git init @@ -39,7 +51,7 @@ pnpm init - + ```bash git init @@ -48,7 +60,7 @@ yarn init - + ```bash git init @@ -58,35 +70,103 @@ npm init -- **Step 3**: Install VuePress locally +- Install VuePress - + ```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 ``` - + ```bash +# install vuepress yarn add -D vuepress@next +# install bundler and theme +yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next ``` - + ```bash +# install vuepress npm install -D vuepress@next +# install bundler and theme +npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next ``` -- **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: + + + ```bash -echo 'node_modules' >> .gitignore -echo '.temp' >> .gitignore -echo '.cache' >> .gitignore +pnpm docs:dev ``` -- **Step 6**: Create your first document + + + ```bash -mkdir docs -echo '# Hello VuePress' > docs/README.md +yarn docs:dev ``` -- **Step 7**: Serve the documentation site in the local server + + + + +```bash +npm run docs:dev +``` + + + + +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: - + ```bash -pnpm docs:dev +pnpm docs:build ``` - + ```bash -yarn docs:dev +yarn docs:build ``` - + ```bash -npm run docs:dev +npm run docs:build ``` -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). diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md index 0ec8175b..26f180e1 100644 --- a/docs/guide/i18n.md +++ b/docs/guide/i18n.md @@ -51,9 +51,10 @@ VuePress does not restrict how themes provide multi-language support, so each th If you are using default theme, the multi-language support is the same as above: ```ts -import { defaultTheme } from 'vuepress' +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' -export default { +export default defineUserConfig({ theme: defaultTheme({ locales: { '/': { @@ -64,7 +65,7 @@ export default { }, }, }), -} +}) ``` ::: tip diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index 72ad53fd..307cc8ee 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -163,8 +163,9 @@ You can highlight specified lines of your code blocks by adding line ranges mark **Input** ````md -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' +```ts{1,7-9} +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' export default defineUserConfig({ title: 'Hello, VuePress', @@ -178,8 +179,9 @@ export default defineUserConfig({ **Output** -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' +```ts{1,7-9} +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' export default defineUserConfig({ title: 'Hello, VuePress', diff --git a/docs/guide/migration.md b/docs/guide/migration.md index f0c15860..689acded 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -47,7 +47,7 @@ Using a theme via string is not supported. Import the theme directly. - }, - } -+ import { defaultTheme } from 'vuepress' ++ import { defaultTheme } from '@vuepress/theme-default' + export default { + theme: defaultTheme({ + // default theme config diff --git a/docs/guide/theme.md b/docs/guide/theme.md index 0271e3d9..9e6e0941 100644 --- a/docs/guide/theme.md +++ b/docs/guide/theme.md @@ -4,16 +4,15 @@ VuePress theme can provide layouts, styles and many other features for you, help ## Default Theme -VuePress has a default theme out of the box, which is applied to our documentation site you are currently browsing. +VuePress provides a default theme, which is applied to our documentation site you are currently browsing. -If you don't specify the theme to use, the default theme will be used automatically. - -To configure the default theme, you need to import and use it in your config file via the [theme](../reference/config.md#theme) option: +You need to import and use it in your config file via the [theme](../reference/config.md#theme) option: ```ts -import { defaultTheme } from 'vuepress' +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' -export default { +export default defineUserConfig({ theme: defaultTheme({ // default theme config navbar: [ @@ -23,7 +22,7 @@ export default { }, ], }), -} +}) ``` The default theme provides basic but useful features for documentation site, you can check out [Default Theme Config Reference](../reference/default-theme/config.md) for a full list of config. diff --git a/docs/reference/default-theme/components.md b/docs/reference/default-theme/components.md index 9e1ff8f1..d6877499 100644 --- a/docs/reference/default-theme/components.md +++ b/docs/reference/default-theme/components.md @@ -61,7 +61,7 @@ ````md - + ```bash:no-line-numbers pnpm install @@ -69,7 +69,7 @@ pnpm install - + ```bash:no-line-numbers yarn install @@ -77,7 +77,7 @@ yarn install - + ```bash:no-line-numbers npm install @@ -90,7 +90,7 @@ npm install **Output** - + ```bash:no-line-numbers pnpm install @@ -98,7 +98,7 @@ pnpm install - + ```bash:no-line-numbers yarn install @@ -106,7 +106,7 @@ yarn install - + ```bash:no-line-numbers npm install diff --git a/docs/reference/default-theme/extending.md b/docs/reference/default-theme/extending.md index 52c1cb02..aecfe6ca 100644 --- a/docs/reference/default-theme/extending.md +++ b/docs/reference/default-theme/extending.md @@ -70,8 +70,9 @@ Default theme has registered [alias](../plugin-api.md#alias) for every [non-glob Then, if you want to replace the `HomeFooter.vue` component, just override the alias in your config file `.vuepress/config.ts`: ```ts +import { defaultTheme } from '@vuepress/theme-default' import { getDirname, path } from '@vuepress/utils' -import { defaultTheme, defineUserConfig } from 'vuepress' +import { defineUserConfig } from 'vuepress' const __dirname = getDirname(import.meta.url) diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md index c10d9b0f..efdcdb28 100644 --- a/docs/zh/guide/bundler.md +++ b/docs/zh/guide/bundler.md @@ -1,67 +1,63 @@ # 打包工具 -VuePress 一直以来都在使用 [Webpack](https://webpack.js.org/) 作为打包工具来进行网站的开发和构建。从 VuePress v2 开始，我们还支持使用其他的打包工具，并且现在使用 [Vite](https://vitejs.dev/) 作为默认的打包工具。当然，你仍然可以选择使用 Webpack 。 +VuePress 支持使用 [Vite](https://vitejs.dev/) 或 [Webpack](https://webpack.js.org/) 作为打包工具来进行网站的开发和构建。你可以根据自己的喜好来选择使用哪个打包工具，并且不需要进行额外的配置。 -## 选择一个打包工具 +## 安装打包工具 -在使用 [vuepress](https://www.npmjs.com/package/vuepress) 包时，会自动安装和使用 Vite 打包工具。 - -如果你想改为使用 Webpack 打包工具，那么你可以移除它，改为安装 [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) 包： +在安装 [vuepress](https://www.npmjs.com/package/vuepress) 包时，并不会自动安装打包工具，你需要选择并安装一个打包工具。 - + ```bash -pnpm uninstall vuepress -pnpm add -D vuepress-webpack@next +# 安装 vite 打包工具 +pnpm add -D vuepress@next @vuepress/bundler-vite@next +# 安装 webpack 打包工具 +pnpm add -D vuepress@next @vuepress/bundler-webpack@next ``` - + ```bash -yarn remove vuepress -yarn add -D vuepress-webpack@next +# 安装 vite 打包工具 +yarn add -D vuepress@next @vuepress/bundler-vite@next +# 安装 webpack 打包工具 +yarn add -D vuepress@next @vuepress/bundler-webpack@next ``` - + ```bash -npm uninstall vuepress -npm install -D vuepress-webpack@next +# 安装 vite 打包工具 +npm install -D vuepress@next @vuepress/bundler-vite@next +# 安装 webpack 打包工具 +npm install -D vuepress@next @vuepress/bundler-webpack@next ``` -::: tip -实际上， [vuepress](https://www.npmjs.com/package/vuepress) 包只是 [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) 包的一个封装而已。 -::: - -## 配置打包工具 +## 使用打包工具 一般情况下，你不要任何额外配置就可以使用打包工具，因为我们已经帮你配置好了它们。 -通过 [bundler](../reference/config.md#bundler) 配置项，你可以对打包工具进行进阶配置： +你只需要通过 [bundler](../reference/config.md#bundler) 配置项指定打包工具即可： ```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(), } ``` -你可以参考 [打包工具 > Vite](../reference/bundler/vite.md) 和 [打包工具 > Webpack](../reference/bundler/webpack.md) 来查看对应打包工具的所有配置项。 +当你需要对打包工具进行进阶配置时，只需要传入对应的配置项即可： + +- [打包工具 > Vite](../reference/bundler/vite.md) +- [打包工具 > Webpack](../reference/bundler/webpack.md) diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md index d127edb8..1c54a56a 100644 --- a/docs/zh/guide/configuration.md +++ b/docs/zh/guide/configuration.md @@ -2,17 +2,6 @@ ## 配置文件 -如果没有任何配置，你的 VuePress 站点仅有一些最基础的功能。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 `.vuepress` 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样： - -``` -├─ docs -│ ├─ .vuepress -│ │ └─ config.js -│ └─ README.md -├─ .gitignore -└─ package.json -``` - VuePress 站点的基本配置文件是 `.vuepress/config.js` ，但也同样支持 TypeScript 配置文件。你可以使用 `.vuepress/config.ts` 来得到更好的类型提示。 具体而言，我们对于配置文件的路径有着约定（按照优先顺序）： @@ -29,15 +18,20 @@ VuePress 站点的基本配置文件是 `.vuepress/config.js` ，但也同样支 你也可以通过 [命令行接口](../reference/cli.md) 的 `--config` 选项来指定配置文件： ```sh -vuepress dev docs --config my-config.js +vuepress dev docs --config my-config.ts ``` 一个基础的配置文件是这样的： ```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: 'zh-CN', title: '你好， VuePress ！', description: '这是我的第一个 VuePress 站点', diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 0cbc1e4e..969ffebf 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -4,7 +4,13 @@ VuePress v2 目前仍处于 RC (Release Candidate) 阶段。你已经可以用它来构建你的站点，但是它的配置和 API 还不够稳定，有可能会发生一些微小的 Breaking Changes 。因此，在每次更新 RC 版本之后，请一定要仔细阅读 [更新日志](https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md)。 ::: -## 依赖环境 +## 在线试一试 + +你可以通过 [StackBlitz](https://stackblitz.com/fork/vuepress) 在你的浏览器里直接使用 VuePress 。 + +## 安装 + +### 依赖环境 - [Node.js v18.16.0+](https://nodejs.org/) - 包管理器，如 [pnpm](https://pnpm.io/zh/)、[yarn](https://classic.yarnpkg.com/en/)、[npm](https://www.npmjs.com/) 等。 @@ -16,21 +22,27 @@ VuePress v2 目前仍处于 RC (Release Candidate) 阶段。你已经可以用 ::: -## 手动安装 +### 创建项目 + +#### 通过命令行创建 -这一章节会帮助你从头搭建一个简单的 VuePress 文档网站。如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 开始。 +TODO -- **步骤 1**: 创建并进入一个新目录 +#### 手动创建 + +这一章节会帮助你从头搭建一个简单的 VuePress 文档网站。 + +- 创建并进入一个新目录 ```bash mkdir vuepress-starter cd vuepress-starter ``` -- **步骤 2**: 初始化项目 +- 初始化项目 - + ```bash git init @@ -39,7 +51,7 @@ pnpm init - + ```bash git init @@ -48,7 +60,7 @@ yarn init - + ```bash git init @@ -58,35 +70,103 @@ npm init -- **步骤 3**: 将 VuePress 安装为本地依赖 +- 安装 VuePress - + ```bash +# 安装 vuepress 和必需的 peer dependencies pnpm add -D vuepress@next @vuepress/client@next vue +# 安装打包工具和主题 +pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next ``` - + ```bash +# 安装 vuepress yarn add -D vuepress@next +# 安装打包工具和主题 +yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next ``` - + ```bash +# 安装 vuepress npm install -D vuepress@next +# 安装打包工具和主题 +npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next ``` -- **步骤 4**: 在 `package.json` 中添加一些 [scripts](https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts) +- 创建 `docs` 目录和 `docs/.vuepress` 目录 + +```bash +mkdir docs +mkdir docs/.vuepress +``` + +- 创建 VuePress 配置文件 `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(), +}) +``` + +- 创建你的第一篇文档 + +```bash +echo '# Hello VuePress' > docs/README.md +``` + +## 目录结构 + +创建完成后，你项目的目录结构应该是这样的： + +``` +├─ docs +│ ├─ .vuepress +│ │ └─ config.js +│ └─ README.md +└─ package.json +``` + +`docs` 目录是你放置 Markdown 文件的地方，它同时也会作为 VuePress 的源文件目录。 + +`docs/.vuepress` 目录，即源文件目录下的 `.vuepress` 目录，是放置所有和 VuePress 相关的文件的地方。当前这里只有一个配置文件。默认还会在该目录下生成临时文件、缓存文件和构建输出文件。建议你把它们添加到 `.gitignore` 文件中。 + +::: details 示例 `.gitignore` 文件 + +``` +# VuePress 默认临时文件目录 +.vuepress/.temp +# VuePress 默认缓存目录 +.vuepress/.cache +# VuePress 默认构建生成的静态文件目录 +.vuepress/dist +``` + +::: + +## 开始使用 VuePress + +### 启动开发服务器 + +你可以在 `package.json` 中添加一些 [scripts](https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts) ： ```json { @@ -97,49 +177,70 @@ npm install -D vuepress@next } ``` -- **步骤 5**: 将默认的临时目录和缓存目录添加到 `.gitignore` 文件中 +运行 `docs:dev` 脚本可以启动开发服务器: + + + ```bash -echo 'node_modules' >> .gitignore -echo '.temp' >> .gitignore -echo '.cache' >> .gitignore +pnpm docs:dev ``` -- **步骤 6**: 创建你的第一篇文档 + + + ```bash -mkdir docs -echo '# Hello VuePress' > docs/README.md +yarn docs:dev ``` -- **步骤 7**: 在本地启动服务器来开发你的文档网站 + + + + +```bash +npm run docs:dev +``` + + + + +VuePress 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。 + +### 构建你的网站 + +运行 `docs:build` 脚本可以构建你的网站： - + ```bash -pnpm docs:dev +pnpm docs:build ``` - + ```bash -yarn docs:dev +yarn docs:build ``` - + ```bash -npm run docs:dev +npm run docs:build ``` -VuePress 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。 +在 `docs/.vuepress/dist` 目录中可以找到构建生成的静态文件。你可以查看 [部署](./deployment.md) 来了解如何部署你的网站。 + +## 进一步了解 VuePress + +现在，你应该已经有了一个简单可用的 VuePress 网站。但你可能仍需要阅读后续的指南来更加了解 VuePress 。 -现在，你应该已经有了一个简单可用的 VuePress 文档网站。接下来，了解一下 VuePress [配置](./configuration.md) 相关的内容。 +下一步，前往 [配置](./configuration.md) 了解更多配置文件相关的内容。 diff --git a/docs/zh/guide/i18n.md b/docs/zh/guide/i18n.md index 276164a0..5fb88167 100644 --- a/docs/zh/guide/i18n.md +++ b/docs/zh/guide/i18n.md @@ -51,9 +51,10 @@ VuePress 没有限制主题如何提供多语言支持，因此每个主题可 如果你使用的是默认主题，那么它提供多语言支持的方式和上述是一致的： ```ts -import { defaultTheme } from 'vuepress' +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' -export default { +export default defineUserConfig({ theme: defaultTheme({ locales: { '/': { @@ -64,7 +65,7 @@ export default { }, }, }), -} +}) ``` ::: tip diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md index 6dbf043c..799fe7bf 100644 --- a/docs/zh/guide/markdown.md +++ b/docs/zh/guide/markdown.md @@ -164,8 +164,9 @@ Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-e **输入** ````md -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' +```ts{1,7-9} +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' export default defineUserConfig({ title: '你好， VuePress', @@ -179,8 +180,9 @@ export default defineUserConfig({ **输出** -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' +```ts{1,7-9} +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' export default defineUserConfig({ title: '你好， VuePress', diff --git a/docs/zh/guide/migration.md b/docs/zh/guide/migration.md index 50a86492..08be14c4 100644 --- a/docs/zh/guide/migration.md +++ b/docs/zh/guide/migration.md @@ -47,7 +47,7 @@ VuePress v2 的核心思想和流程是和 v1 一致的，但 v2 API 经过了 - }, - } -+ import { defaultTheme } from 'vuepress' ++ import { defaultTheme } from '@vuepress/theme-default' + export default { + theme: defaultTheme({ + // 默认主题配置 diff --git a/docs/zh/guide/theme.md b/docs/zh/guide/theme.md index c459dc22..1f43290c 100644 --- a/docs/zh/guide/theme.md +++ b/docs/zh/guide/theme.md @@ -4,16 +4,15 @@ VuePress 主题为你提供了布局、样式和其他功能，帮助你专注 ## 默认主题 -VuePress 有一个开箱即用的默认主题，正使用在你当前正在浏览的文档网站上。 +VuePress 提供了一个默认主题，你当前正在浏览的文档网站就是使用的这个默认主题。 -如果你不指定要使用的主题，那么就会自动使用默认主题。 - -为了配置默认主题，你需要在你的配置文件中通过 [theme](../reference/config.md#theme) 配置项来使用它： +你需要在你的配置文件中通过 [theme](../reference/config.md#theme) 配置项来使用它： ```ts -import { defaultTheme } from 'vuepress' +import { defaultTheme } from '@vuepress/theme-default' +import { defineUserConfig } from 'vuepress' -export default { +export default defineUserConfig({ theme: defaultTheme({ // 默认主题配置 navbar: [ @@ -23,7 +22,7 @@ export default { }, ], }), -} +}) ``` 默认主题为文档网站提供了基础且实用的功能，你可以前往 [默认主题配置参考](../reference/default-theme/config.md) 获取全部的配置列表。 diff --git a/docs/zh/reference/default-theme/components.md b/docs/zh/reference/default-theme/components.md index d827ec11..2031e197 100644 --- a/docs/zh/reference/default-theme/components.md +++ b/docs/zh/reference/default-theme/components.md @@ -61,7 +61,7 @@ ````md - + ```bash:no-line-numbers pnpm install @@ -69,7 +69,7 @@ pnpm install - + ```bash:no-line-numbers yarn install @@ -77,7 +77,7 @@ yarn install - + ```bash:no-line-numbers npm install @@ -90,7 +90,7 @@ npm install **输出** - + ```bash:no-line-numbers pnpm install @@ -98,7 +98,7 @@ pnpm install - + ```bash:no-line-numbers yarn install @@ -106,7 +106,7 @@ yarn install - + ```bash:no-line-numbers npm install diff --git a/docs/zh/reference/default-theme/extending.md b/docs/zh/reference/default-theme/extending.md index 0b57b86e..6fff5fa8 100644 --- a/docs/zh/reference/default-theme/extending.md +++ b/docs/zh/reference/default-theme/extending.md @@ -70,8 +70,9 @@ import ParentLayout from '@vuepress/theme-default/layouts/Layout.vue' 接下来，如果你想要替换 `HomeFooter.vue` 组件，只需要在配置文件 `.vuepress/config.ts` 中覆盖这个别名即可： ```ts +import { defaultTheme } from '@vuepress/theme-default' import { getDirname, path } from '@vuepress/utils' -import { defaultTheme, defineUserConfig } from 'vuepress' +import { defineUserConfig } from 'vuepress' const __dirname = getDirname(import.meta.url)