diff --git a/docs/README.md b/docs/README.md index 1c2d0de8df..d6919a4a0d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,7 @@ features: - title: Themes details: Providing a default theme out of the box. You can also choose a community theme or create your own one. - title: Plugins - details: Flexible plugin API, allowing plugins to provide lots of plug-and-play features for your site. + details: Flexible plugin API, allowing plugins to provide lots of plug-and-play features for your site. - title: Bundlers details: Default bundler is Vite, while Webpack is also supported. Choose the one you like! footer: MIT Licensed | Copyright © 2018-present Evan You @@ -28,7 +28,25 @@ footer: MIT Licensed | Copyright © 2018-present Evan You ### As Easy as 1, 2, 3 - + + +```bash +# install in your project +pnpm add -D vuepress@next @vuepress/client@next vue + +# create a markdown file +echo '# Hello VuePress' > README.md + +# start writing +pnpm vuepress dev + +# build to static files +pnpm vuepress build +``` + + + + ```bash # install in your project diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md index 6e393a9fa9..1a8640dc0b 100644 --- a/docs/guide/bundler.md +++ b/docs/guide/bundler.md @@ -9,7 +9,16 @@ When using the [vuepress](https://www.npmjs.com/package/vuepress) package, Vite 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: - + + +```bash +pnpm remove vuepress +pnpm add -D vuepress-webpack@next +``` + + + + ```bash yarn remove vuepress diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index a7b5c1cd8f..db417a5314 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -4,7 +4,7 @@ The following guides are based on some shared assumptions: - You are placing your Markdown source files inside the `docs` directory of your project; - You are using the default build output location (`.vuepress/dist`); -- You are using [yarn classic](https://classic.yarnpkg.com/en/) as package manager, while npm is also supported; +- You are using as [pnpm](https://pnpm.io) package manager, while npm and yarn are also supported; - VuePress is installed as a local dependency in your project, and you have setup the following script in `package.json`: ```json @@ -19,13 +19,13 @@ The following guides are based on some shared assumptions: 1. Set the correct [base](../reference/config.md#base) config. - If you are deploying to `https://.github.io/`, you can omit this step as `base` defaults to `"/"`. + If you are deploying to `https://.github.io/`, you can omit this step as `base` defaults to `"/"`. - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `"//"`. + If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `"//"`. 2. Choose your preferred CI tools. Here we take [GitHub Actions](https://github.com/features/actions) as an example. - Create `.github/workflows/docs.yml` to set up the workflow. + Create `.github/workflows/docs.yml` to set up the workflow. ::: details Click to expand sample config ```yaml @@ -43,36 +43,30 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: # fetch all commits to get last updated time or other git log info fetch-depth: 0 - - name: Setup Node.js - uses: actions/setup-node@v1 + - name: Setup pnpm + uses: pnpm/action-setup@v2 with: - # choose node.js version to use - node-version: '14' + # choose pnpm version to use + version: 7 + # install deps with pnpm + run_install: true - # cache node_modules - - name: Cache dependencies - uses: actions/cache@v2 - id: yarn-cache + - name: Setup Node.js + uses: actions/setup-node@v3 with: - path: | - **/node_modules - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} - restore-keys: | - ${{ runner.os }}-yarn- - - # install dependencies if the cache did not hit - - name: Install dependencies - if: steps.yarn-cache.outputs.cache-hit != 'true' - run: yarn --frozen-lockfile + # choose node.js version to use + node-version: 18 + # cache deps for pnpm + cache: pnpm # run build script - name: Build VuePress site - run: yarn docs:build + run: pnpm docs:build # please check out the docs of the workflow for more details # @see https://github.com/crazy-max/ghaction-github-pages @@ -97,35 +91,43 @@ Please refer to [GitHub Pages official guide](https://pages.github.com/) for mor 1. Set the correct [base](../reference/config.md#base) config. - If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. + If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. - If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `"//"`. + If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `"//"`. 2. Create `.gitlab-ci.yml` to set up [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) workflow. ::: details Click to expand sample config ```yaml # choose a docker image to use -image: node:14-buster +image: node:18-buster pages: # trigger deployment on every push to main branch only: - - main + - main # cache node_modules cache: + key: + files: + - pnpm-lock.yaml paths: - - node_modules/ + - .pnpm-store + + # Install pnpm + before_script: + - curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm@7 + - pnpm config set store-dir .pnpm-store # install dependencies and run build script script: - - yarn --frozen-lockfile - - yarn docs:build --dest public + - pnpm i --frozen-lockfile + - pnpm docs:build --dest public artifacts: paths: - - public + - public ``` ::: @@ -160,7 +162,7 @@ Please refer to [GitLab Pages official guide](https://docs.gitlab.com/ce/user/pr } ``` -3. After running `yarn docs:build`, deploy using the command `firebase deploy`. +3. After running `pnpm docs:build`, deploy using the command `firebase deploy`. ::: tip Please refer to [Firebase CLI official guide](https://firebase.google.com/docs/cli) for more details. @@ -198,12 +200,12 @@ See [Layer0 Documentation > Framework Guides > VuePress](https://docs.layer0.co/ 1. On [Netlify](https://netlify.com), set up a new project from GitHub with the following settings: - - **Build Command:** `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` + - **Build Command:** `pnpm docs:build` + - **Publish directory:** `docs/.vuepress/dist` 2. Set [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) to choose node version: - - `NODE_VERSION`: 14 + - `NODE_VERSION`: 14 3. Hit the deploy button. @@ -211,8 +213,8 @@ See [Layer0 Documentation > Framework Guides > VuePress](https://docs.layer0.co/ 1. Go to [Vercel](https://vercel.com), set up a new project from GitHub with the following settings: - - **FRAMEWORK PRESET:** `Other` - - **BUILD COMMAND:** `yarn docs:build` - - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` - + - **FRAMEWORK PRESET:** `Other` + - **BUILD COMMAND:** `pnpm docs:build` + - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` + 2. Hit the deploy button. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index b35535a616..67c62b1031 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -28,7 +28,16 @@ cd vuepress-starter - **Step 2**: Initialize your project - + + +```bash +git init +pnpm init +``` + + + + ```bash git init @@ -50,7 +59,15 @@ npm init - **Step 3**: Install VuePress locally - + + +```bash +pnpm add -D vuepress@next @vuepress/client@next vue +``` + + + + ```bash yarn add -D vuepress@next @@ -96,7 +113,15 @@ echo '# Hello VuePress' > docs/README.md - **Step 7**: Serve the documentation site in the local server - + + +```bash +pnpm docs:dev +``` + + + + ```bash yarn docs:dev @@ -113,6 +138,6 @@ 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. +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. By now, you should have a basic but functional VuePress documentation site. Next, learn about the basics of [configuration](./configuration.md) in VuePress. diff --git a/docs/reference/default-theme/components.md b/docs/reference/default-theme/components.md index d4d3175229..931fb27b3f 100644 --- a/docs/reference/default-theme/components.md +++ b/docs/reference/default-theme/components.md @@ -59,10 +59,18 @@ ````md + + +```bash:no-line-numbers +pnpm install +``` + + + ```bash:no-line-numbers -yarn +yarn install ``` @@ -80,10 +88,18 @@ npm install **Output** + + +```bash:no-line-numbers +pnpm install +``` + + + ```bash:no-line-numbers -yarn +yarn install ``` diff --git a/docs/zh/README.md b/docs/zh/README.md index 32ad152f51..8e5618719f 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -28,7 +28,25 @@ footer: MIT Licensed | Copyright © 2018-present Evan You ### 像数 1, 2, 3 一样容易 - + + +```bash +# 在你的项目中安装 +pnpm add -D vuepress@next @vuepress/client@next vue + +# 新建一个 markdown 文件 +echo '# Hello VuePress' > README.md + +# 开始写作 +pnpm vuepress dev + +# 构建静态文件 +pnpm vuepress build +``` + + + + ```bash # 在你的项目中安装 diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md index dede01037e..8579829d10 100644 --- a/docs/zh/guide/bundler.md +++ b/docs/zh/guide/bundler.md @@ -9,7 +9,16 @@ VuePress 一直以来都在使用 [Webpack](https://webpack.js.org/) 作为打 如果你想改为使用 Webpack 打包工具，那么你可以移除它，改为安装 [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) 包： - + + +```bash +pnpm uninstall vuepress +pnpm add -D vuepress-webpack@next +``` + + + + ```bash yarn remove vuepress diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 53ae7f8376..fa4e1f9063 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -4,7 +4,7 @@ - Markdown 源文件放置在你项目的 `docs` 目录； - 使用的是默认的构建输出目录 (`.vuepress/dist`) ； -- 使用 [Yarn classic](https://classic.yarnpkg.com/zh-Hans/) 作为包管理器，当然也可以使用 NPM 。 +- 使用 [pnpm](https://pnpm.io/zh/) 作为包管理器，当然也支持使用 npm 或 yarn 。 - VuePress 作为项目依赖安装，并在 `package.json` 中配置了如下脚本： ```json @@ -43,36 +43,30 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 fetch-depth: 0 - - name: Setup Node.js - uses: actions/setup-node@v1 + - name: Setup pnpm + uses: pnpm/action-setup@v2 with: - # 选择要使用的 node 版本 - node-version: '14' + # 选择要使用的 pnpm 版本 + version: 7 + # 使用 pnpm 安装依赖 + run_install: true - # 缓存 node_modules - - name: Cache dependencies - uses: actions/cache@v2 - id: yarn-cache + - name: Setup Node.js + uses: actions/setup-node@v3 with: - path: | - **/node_modules - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} - restore-keys: | - ${{ runner.os }}-yarn- - - # 如果缓存没有命中，安装依赖 - - name: Install dependencies - if: steps.yarn-cache.outputs.cache-hit != 'true' - run: yarn --frozen-lockfile + # 选择要使用的 node 版本 + node-version: 18 + # 缓存 pnpm 依赖 + cache: pnpm # 运行构建脚本 - name: Build VuePress site - run: yarn docs:build + run: pnpm docs:build # 查看 workflow 的文档来获取更多信息 # @see https://github.com/crazy-max/ghaction-github-pages @@ -89,7 +83,6 @@ jobs: ``` ::: - ::: tip 请参考 [GitHub Pages 官方指南](https://pages.github.com/) 来获取更多信息。 ::: @@ -107,26 +100,34 @@ jobs: ::: details 点击展开配置样例 ```yaml # 选择你要使用的 docker 镜像 -image: node:14-buster +image: node:18-buster pages: # 每当 push 到 main 分支时触发部署 only: - - main + - main # 缓存 node_modules cache: + key: + files: + - pnpm-lock.yaml paths: - - node_modules/ + - .pnpm-store + + # 安装 pnpm + before_script: + - curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm@7 + - pnpm config set store-dir .pnpm-store # 安装依赖并运行构建脚本 script: - - yarn --frozen-lockfile - - yarn docs:build --dest public + - pnpm install --frozen-lockfile + - pnpm docs:build --dest public artifacts: paths: - - public + - public ``` ::: @@ -161,7 +162,7 @@ pages: } ``` -3. 在执行了 `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。 +3. 在执行了 `pnpm docs:build` 后, 使用 `firebase deploy` 指令来部署。 ::: tip 请参考 [Firebase CLI 官方指南](https://firebase.google.com/docs/cli) 来获取更多信息。 @@ -199,12 +200,12 @@ heroku login 1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - **Build Command:** `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` + - **Build Command:** `pnpm docs:build` + - **Publish directory:** `docs/.vuepress/dist` 2. 设置 [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) 来选择 Node 版本： - - `NODE_VERSION`: 14 + - `NODE_VERSION`: 14 3. 点击 deploy 按钮。 @@ -212,9 +213,9 @@ heroku login 1. 前往 [Vercel](https://vercel.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - **FRAMEWORK PRESET:** `Other` - - **BUILD COMMAND:** `yarn docs:build` - - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` + - **FRAMEWORK PRESET:** `Other` + - **BUILD COMMAND:** `pnpm docs:build` + - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` 2. 点击 deploy 按钮。 @@ -227,7 +228,7 @@ heroku login 1. 全局安装 CloudBase CLI ： ```bash -npm install -g @cloudbase/cli +pnpm install -g @cloudbase/cli ``` 2. 在项目根目录运行以下命令一键部署 VuePress 应用，在部署之前可以先 [开通环境](https://console.cloud.tencent.com/tcb/env/index?tdl_anchor=ad&tdl_site=vuejs)： @@ -237,11 +238,11 @@ cloudbase init --without-template cloudbase framework:deploy ``` - CloudBase CLI 首先会跳转到控制台进行登录授权，然后将会交互式进行确认。 +CloudBase CLI 首先会跳转到控制台进行登录授权，然后将会交互式进行确认。 - 确认信息后会立即进行部署，部署完成后，可以获得一个自动 SSL，CDN 加速的网站应用，你也可以搭配使用 GitHub Action 来持续部署 GitHub 上的 VuePress 应用。 +确认信息后会立即进行部署，部署完成后，可以获得一个自动 SSL，CDN 加速的网站应用，你也可以搭配使用 GitHub Action 来持续部署 GitHub 上的 VuePress 应用。 - 也可以使用 `cloudbase init --template vuepress` 快速创建和部署一个新的 VuePress 应用。 +也可以使用 `cloudbase init --template vuepress` 快速创建和部署一个新的 VuePress 应用。 ::: tip 更多详细信息请查看 CloudBase Framework 的[部署项目示例](https://github.com/TencentCloudBase/cloudbase-framework?site=vuepress#%E9%A1%B9%E7%9B%AE%E7%A4%BA%E4%BE%8B) diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 1f65c227a1..6b6a2c70be 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -10,25 +10,35 @@ VuePress v2 目前仍处于 `beta` 阶段。你已经可以用它来构建你的 - [Yarn v1 classic](https://classic.yarnpkg.com/zh-Hans/) （可选） ::: tip + - 使用 [pnpm](https://pnpm.io/zh/) 时，你可能需要安装 `vue` 和 `@vuepress/client` 作为 peer-dependencies ，即 `pnpm add -D vue @vuepress/client@next` 。 - 使用 [yarn 2](https://yarnpkg.com/) 时，你需要在 [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) 文件中设置 `nodeLinker: 'node-modules'` 。 -::: + ::: ## 手动安装 这一章节会帮助你从头搭建一个简单的 VuePress 文档网站。如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 开始。 -- **步骤1**: 创建并进入一个新目录 +- **步骤 1**: 创建并进入一个新目录 ```bash mkdir vuepress-starter cd vuepress-starter ``` -- **步骤2**: 初始化项目 +- **步骤 2**: 初始化项目 - + + +```bash +git init +pnpm init +``` + + + + ```bash git init @@ -47,11 +57,18 @@ npm init - -- **步骤3**: 将 VuePress 安装为本地依赖 +- **步骤 3**: 将 VuePress 安装为本地依赖 - + + +```bash +pnpm add -D vuepress@next @vuepress/client@next vue +``` + + + + ```bash yarn add -D vuepress@next @@ -68,7 +85,7 @@ npm install -D vuepress@next -- **步骤4**: 在 `package.json` 中添加一些 [scripts](https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts) +- **步骤 4**: 在 `package.json` 中添加一些 [scripts](https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts) ```json { @@ -79,7 +96,7 @@ npm install -D vuepress@next } ``` -- **步骤5**: 将默认的临时目录和缓存目录添加到 `.gitignore` 文件中 +- **步骤 5**: 将默认的临时目录和缓存目录添加到 `.gitignore` 文件中 ```bash echo 'node_modules' >> .gitignore @@ -87,17 +104,25 @@ echo '.temp' >> .gitignore echo '.cache' >> .gitignore ``` -- **步骤6**: 创建你的第一篇文档 +- **步骤 6**: 创建你的第一篇文档 ```bash mkdir docs echo '# Hello VuePress' > docs/README.md ``` -- **步骤7**: 在本地启动服务器来开发你的文档网站 +- **步骤 7**: 在本地启动服务器来开发你的文档网站 - + + +```bash +pnpm docs:dev +``` + + + + ```bash yarn docs:dev @@ -114,6 +139,6 @@ npm run docs:dev - VuePress 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。 +VuePress 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。 -现在，你应该已经有了一个简单可用的 VuePress 文档网站。接下来，了解一下 VuePress [配置](./configuration.md) 相关的内容。 \ No newline at end of file +现在，你应该已经有了一个简单可用的 VuePress 文档网站。接下来，了解一下 VuePress [配置](./configuration.md) 相关的内容。 diff --git a/docs/zh/reference/default-theme/components.md b/docs/zh/reference/default-theme/components.md index ff994a05b0..cad204ba16 100644 --- a/docs/zh/reference/default-theme/components.md +++ b/docs/zh/reference/default-theme/components.md @@ -59,10 +59,18 @@ ````md + + +```bash:no-line-numbers +pnpm install +``` + + + ```bash:no-line-numbers -yarn +yarn install ``` @@ -80,10 +88,18 @@ npm install **输出** + + +```bash:no-line-numbers +pnpm install +``` + + + ```bash:no-line-numbers -yarn +yarn install ```