From b90f4b2c58b8e4588d81e61ad5699d3df1884d30 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Sun, 28 Aug 2022 13:59:19 +0800 Subject: [PATCH 01/13] docs: add pnpm docs --- docs/README.md | 22 +++- docs/guide/bundler.md | 11 +- docs/guide/deployment.md | 115 +++++++++++++----- docs/guide/getting-started.md | 33 ++++- docs/reference/default-theme/components.md | 20 ++- docs/zh/README.md | 20 ++- docs/zh/guide/deployment.md | 82 +++++++++++-- docs/zh/guide/getting-started.md | 53 +++++--- docs/zh/reference/default-theme/components.md | 20 ++- 9 files changed, 308 insertions(+), 68 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1c2d0de8df..bf1228cc6f 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 vue @vuepress/client@next vuepress@next + +# 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..8852a329bc 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -19,15 +19,19 @@ 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 name: docs @@ -43,27 +47,76 @@ 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 pnpm + uses: pnpm/action-setup@v2 + with: + # choose pnpm version to use + version: 7 + # install deps with pnpm + run_install: true + - name: Setup Node.js - uses: actions/setup-node@v1 + uses: actions/setup-node@v3 with: # choose node.js version to use - node-version: '14' + node-version: 16 + # cache deps for pnpm + cache: pnpm - # cache node_modules - - name: Cache dependencies - uses: actions/cache@v2 - id: yarn-cache + # run build script + - name: Build VuePress site + run: pnpm docs:build + + # please check out the docs of the workflow for more details + # @see https://github.com/crazy-max/ghaction-github-pages + - name: Deploy to GitHub Pages + uses: crazy-max/ghaction-github-pages@v2 with: - path: | - **/node_modules - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} - restore-keys: | - ${{ runner.os }}-yarn- + # deploy to gh-pages branch + target_branch: gh-pages + # deploy the default output dir of VuePress + build_dir: docs/.vuepress/dist + env: + # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + + + + + +```yaml +name: docs + +on: + # trigger deployment on every push to main branch + push: + branches: [main] + # trigger deployment manually + workflow_dispatch: + +jobs: + docs: + runs-on: ubuntu-latest + + steps: + - 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@v3 + with: + # choose node.js version to use + node-version: '14' + # cache deps for yarn + cache: yarn # install dependencies if the cache did not hit - name: Install dependencies @@ -87,6 +140,10 @@ jobs: # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` + + + + ::: ::: tip @@ -97,9 +154,9 @@ 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. @@ -111,21 +168,21 @@ image: node:14-buster pages: # trigger deployment on every push to main branch only: - - main + - main # cache node_modules cache: paths: - - node_modules/ + - node_modules/ # install dependencies and run build script script: - - yarn --frozen-lockfile - - yarn docs:build --dest public + - yarn --frozen-lockfile + - yarn docs:build --dest public artifacts: paths: - - public + - public ``` ::: @@ -198,12 +255,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:** `yarn 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 +268,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:** `yarn 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 3cf12a92ca..d933c5c3fc 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -24,7 +24,16 @@ cd vuepress-starter - **Step 2**: Initialize your project - + + +```bash +git init +pnpm init +``` + + + + ```bash git init @@ -46,7 +55,15 @@ npm init - **Step 3**: Install VuePress locally - + + +```bash +pnpm add -D vue @vuepress/client@next vuepress@next +``` + + + + ```bash yarn add -D vuepress@next @@ -92,7 +109,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 @@ -109,6 +134,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..333986cb25 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 +# install in your project +pnpm add -D vue @vuepress/client@next vuepress@next + +# create a markdown file +echo '# Hello VuePress' > README.md + +# start writing +pnpm vuepress dev + +# build to static files +pnpm vuepress build +``` + + + + ```bash # 在你的项目中安装 diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 53ae7f8376..d391c9ba1e 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -28,6 +28,10 @@ 创建 `.github/workflows/docs.yml` 文件来配置工作流。 ::: details 点击展开配置样例 + + + + ```yaml name: docs @@ -43,27 +47,76 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 fetch-depth: 0 + - name: Setup pnpm + uses: pnpm/action-setup@v2 + with: + # 选择要使用的 pnpm 版本 + version: 7 + # 使用 pnpm 安装依赖 + run_install: true + - name: Setup Node.js - uses: actions/setup-node@v1 + uses: actions/setup-node@v3 with: # 选择要使用的 node 版本 - node-version: '14' + node-version: 16 + # 缓存 pnpm 依赖 + cache: pnpm - # 缓存 node_modules - - name: Cache dependencies - uses: actions/cache@v2 - id: yarn-cache + # 运行构建脚本 + - name: Build VuePress site + run: pnpm docs:build + + # 查看 workflow 的文档来获取更多信息 + # @see https://github.com/crazy-max/ghaction-github-pages + - name: Deploy to GitHub Pages + uses: crazy-max/ghaction-github-pages@v2 with: - path: | - **/node_modules - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} - restore-keys: | - ${{ runner.os }}-yarn- + # 部署到 gh-pages 分支 + target_branch: gh-pages + # 部署目录为 VuePress 的默认输出目录 + build_dir: docs/.vuepress/dist + env: + # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + + + + + +```yaml +name: docs + +on: + # 每当 push 到 main 分支时触发部署 + push: + branches: [main] + # 手动触发部署 + workflow_dispatch: + +jobs: + docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + with: + # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + # 选择要使用的 node 版本 + node-version: '14' + # 缓存 yarn 依赖 + cache: yarn # 如果缓存没有命中，安装依赖 - name: Install dependencies @@ -87,8 +140,11 @@ jobs: # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` -::: + + + +::: ::: tip 请参考 [GitHub Pages 官方指南](https://pages.github.com/) 来获取更多信息。 diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 1597f660cf..a59893714b 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -6,25 +6,35 @@ - [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 @@ -43,11 +53,18 @@ npm init - -- **步骤3**: 将 VuePress 安装为本地依赖 +- **步骤 3**: 将 VuePress 安装为本地依赖 - + + +```bash +pnpm add -D vuepress@next vue @vuepress/client@next +``` + + + + ```bash yarn add -D vuepress@next @@ -64,7 +81,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 { @@ -75,7 +92,7 @@ npm install -D vuepress@next } ``` -- **步骤5**: 将默认的临时目录和缓存目录添加到 `.gitignore` 文件中 +- **步骤 5**: 将默认的临时目录和缓存目录添加到 `.gitignore` 文件中 ```bash echo 'node_modules' >> .gitignore @@ -83,17 +100,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 @@ -110,6 +135,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 ``` From c97b6aef9cb8ea664e38e4569873ac32272c1303 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Wed, 19 Oct 2022 09:50:48 +0800 Subject: [PATCH 02/13] Update docs/zh/guide/deployment.md --- docs/zh/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index d391c9ba1e..0d07c04309 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -56,7 +56,7 @@ jobs: uses: pnpm/action-setup@v2 with: # 选择要使用的 pnpm 版本 - version: 7 + version: 8 # 使用 pnpm 安装依赖 run_install: true From fdb86d83b0e278160b732833377a090e53bc5bfb Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Wed, 19 Oct 2022 09:50:53 +0800 Subject: [PATCH 03/13] Update docs/guide/deployment.md --- docs/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 8852a329bc..e527c4b9b3 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -56,7 +56,7 @@ jobs: uses: pnpm/action-setup@v2 with: # choose pnpm version to use - version: 7 + version: 8 # install deps with pnpm run_install: true From 3d5d30e92b0749810719da64489e3c39b44ab27a Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:27 +0800 Subject: [PATCH 04/13] Update docs/guide/deployment.md --- docs/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index e527c4b9b3..7ba9105a46 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -114,7 +114,7 @@ jobs: uses: actions/setup-node@v3 with: # choose node.js version to use - node-version: '14' + node-version: 18 # cache deps for yarn cache: yarn From 4b7395df3fe31f1dcc3ba212ae1fb397a5f6a84f Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:33 +0800 Subject: [PATCH 05/13] Update docs/guide/deployment.md --- docs/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 7ba9105a46..a3b8899451 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -64,7 +64,7 @@ jobs: uses: actions/setup-node@v3 with: # choose node.js version to use - node-version: 16 + node-version: 18 # cache deps for pnpm cache: pnpm From 3860aff66c5e33d9dffe2b3b7d764dc6fc6aff91 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:38 +0800 Subject: [PATCH 06/13] Update docs/guide/deployment.md --- docs/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index a3b8899451..015287875a 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -56,7 +56,7 @@ jobs: uses: pnpm/action-setup@v2 with: # choose pnpm version to use - version: 8 + version: 7 # install deps with pnpm run_install: true From 977deee2a32714236762667f010f3ed3818bf041 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:43 +0800 Subject: [PATCH 07/13] Update docs/zh/guide/deployment.md --- docs/zh/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 0d07c04309..d391c9ba1e 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -56,7 +56,7 @@ jobs: uses: pnpm/action-setup@v2 with: # 选择要使用的 pnpm 版本 - version: 8 + version: 7 # 使用 pnpm 安装依赖 run_install: true From 0b896764d8d91776f4ecdc4abb5f4c7ad642c52f Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:48 +0800 Subject: [PATCH 08/13] Update docs/zh/guide/deployment.md --- docs/zh/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index d391c9ba1e..4ced575a34 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -114,7 +114,7 @@ jobs: uses: actions/setup-node@v3 with: # 选择要使用的 node 版本 - node-version: '14' + node-version: 18 # 缓存 yarn 依赖 cache: yarn From 259d67ba1a50c036bed230cba5dd639c7a7616f2 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Mon, 7 Nov 2022 12:40:53 +0800 Subject: [PATCH 09/13] Update docs/zh/guide/deployment.md --- docs/zh/guide/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 4ced575a34..3a39962dac 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -64,7 +64,7 @@ jobs: uses: actions/setup-node@v3 with: # 选择要使用的 node 版本 - node-version: 16 + node-version: 18 # 缓存 pnpm 依赖 cache: pnpm From 67853b6f869d84687d0aa50973a6b3a0205a8aa8 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Wed, 7 Dec 2022 17:55:54 +0800 Subject: [PATCH 10/13] docs: update docs --- docs/guide/deployment.md | 18 ++++++++++++----- docs/zh/guide/deployment.md | 40 ++++++++++++++++++++++--------------- 2 files changed, 37 insertions(+), 21 deletions(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 015287875a..26c89befb2 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 @@ -163,7 +163,7 @@ Please refer to [GitHub Pages official guide](https://pages.github.com/) for mor ::: 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 @@ -172,13 +172,21 @@ pages: # 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: diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 3a39962dac..f4e1397e38 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 @@ -163,26 +163,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 ``` ::: @@ -255,12 +263,12 @@ heroku login 1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - **Build Command:** `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` + - **Build Command:** `yarn 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 按钮。 @@ -268,9 +276,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:** `yarn docs:build` + - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` 2. 点击 deploy 按钮。 @@ -293,11 +301,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) From 5b97cfca9bd808a26d870c229773f7a32072520f Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Thu, 8 Dec 2022 17:41:10 +0800 Subject: [PATCH 11/13] docs: update docs --- docs/guide/deployment.md | 69 ++----------------------------------- docs/zh/guide/bundler.md | 9 +++++ docs/zh/guide/deployment.md | 69 ++----------------------------------- 3 files changed, 15 insertions(+), 132 deletions(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 26c89befb2..14dc9835be 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -28,10 +28,6 @@ The following guides are based on some shared assumptions: Create `.github/workflows/docs.yml` to set up the workflow. ::: details Click to expand sample config - - - - ```yaml name: docs @@ -85,65 +81,6 @@ jobs: # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` - - - - - -```yaml -name: docs - -on: - # trigger deployment on every push to main branch - push: - branches: [main] - # trigger deployment manually - workflow_dispatch: - -jobs: - docs: - runs-on: ubuntu-latest - - steps: - - 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@v3 - with: - # choose node.js version to use - node-version: 18 - # cache deps for yarn - cache: yarn - - # install dependencies if the cache did not hit - - name: Install dependencies - if: steps.yarn-cache.outputs.cache-hit != 'true' - run: yarn --frozen-lockfile - - # run build script - - name: Build VuePress site - run: yarn docs:build - - # please check out the docs of the workflow for more details - # @see https://github.com/crazy-max/ghaction-github-pages - - name: Deploy to GitHub Pages - uses: crazy-max/ghaction-github-pages@v2 - with: - # deploy to gh-pages branch - target_branch: gh-pages - # deploy the default output dir of VuePress - build_dir: docs/.vuepress/dist - env: - # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - - - - ::: ::: tip @@ -225,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` `yarn docs:build` or `npm run 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. @@ -263,7 +200,7 @@ 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` + - **Build Command:** `npm i -g pnpm@7 && pnpm docs:build` - **Publish directory:** `docs/.vuepress/dist` 2. Set [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) to choose node version: @@ -277,7 +214,7 @@ 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` + - **BUILD COMMAND:** `pnpm docs:build` - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` 2. Hit the deploy button. diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md index dede01037e..2612f527ee 100644 --- a/docs/zh/guide/bundler.md +++ b/docs/zh/guide/bundler.md @@ -9,6 +9,15 @@ 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 diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index f4e1397e38..88df7c9ae1 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -28,10 +28,6 @@ 创建 `.github/workflows/docs.yml` 文件来配置工作流。 ::: details 点击展开配置样例 - - - - ```yaml name: docs @@ -85,65 +81,6 @@ jobs: # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` - - - - - -```yaml -name: docs - -on: - # 每当 push 到 main 分支时触发部署 - push: - branches: [main] - # 手动触发部署 - workflow_dispatch: - -jobs: - docs: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - with: - # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 - fetch-depth: 0 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - # 选择要使用的 node 版本 - node-version: 18 - # 缓存 yarn 依赖 - cache: yarn - - # 如果缓存没有命中，安装依赖 - - name: Install dependencies - if: steps.yarn-cache.outputs.cache-hit != 'true' - run: yarn --frozen-lockfile - - # 运行构建脚本 - - name: Build VuePress site - run: yarn docs:build - - # 查看 workflow 的文档来获取更多信息 - # @see https://github.com/crazy-max/ghaction-github-pages - - name: Deploy to GitHub Pages - uses: crazy-max/ghaction-github-pages@v2 - with: - # 部署到 gh-pages 分支 - target_branch: gh-pages - # 部署目录为 VuePress 的默认输出目录 - build_dir: docs/.vuepress/dist - env: - # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - - - - ::: ::: tip @@ -225,7 +162,7 @@ pages: } ``` -3. 在执行了 `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。 +3. 在执行了 `pnpm docs:build`, `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。 ::: tip 请参考 [Firebase CLI 官方指南](https://firebase.google.com/docs/cli) 来获取更多信息。 @@ -263,7 +200,7 @@ heroku login 1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - **Build Command:** `yarn docs:build` + - **Build Command:** `npm i -g pnpm@7 && pnpm docs:build` - **Publish directory:** `docs/.vuepress/dist` 2. 设置 [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) 来选择 Node 版本： @@ -277,7 +214,7 @@ heroku login 1. 前往 [Vercel](https://vercel.com) ，从 GitHub 创建一个新项目，并进行如下配置： - **FRAMEWORK PRESET:** `Other` - - **BUILD COMMAND:** `yarn docs:build` + - **BUILD COMMAND:** `pnpm docs:build` - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` 2. 点击 deploy 按钮。 From fec2b9bfa5310cbc97d4ade59c23cfb52566a3ba Mon Sep 17 00:00:00 2001 From: meteorlxy Date: Thu, 8 Dec 2022 21:12:34 +0800 Subject: [PATCH 12/13] chore: twaeks --- docs/guide/deployment.md | 4 ++-- docs/zh/guide/deployment.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md index 14dc9835be..db417a5314 100644 --- a/docs/guide/deployment.md +++ b/docs/guide/deployment.md @@ -162,7 +162,7 @@ Please refer to [GitLab Pages official guide](https://docs.gitlab.com/ce/user/pr } ``` -3. After running `pnpm docs:build` `yarn docs:build` or `npm run 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. @@ -200,7 +200,7 @@ 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:** `npm i -g pnpm@7 && pnpm docs:build` + - **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: diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md index 88df7c9ae1..fa4e1f9063 100644 --- a/docs/zh/guide/deployment.md +++ b/docs/zh/guide/deployment.md @@ -4,7 +4,7 @@ - Markdown 源文件放置在你项目的 `docs` 目录； - 使用的是默认的构建输出目录 (`.vuepress/dist`) ； -- 使用 [PNPM](https://pnpm.io/zh/) 作为包管理器，当然也可以使用 NPM 和 YARN 。 +- 使用 [pnpm](https://pnpm.io/zh/) 作为包管理器，当然也支持使用 npm 或 yarn 。 - VuePress 作为项目依赖安装，并在 `package.json` 中配置了如下脚本： ```json @@ -162,7 +162,7 @@ pages: } ``` -3. 在执行了 `pnpm docs:build`, `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。 +3. 在执行了 `pnpm docs:build` 后, 使用 `firebase deploy` 指令来部署。 ::: tip 请参考 [Firebase CLI 官方指南](https://firebase.google.com/docs/cli) 来获取更多信息。 @@ -200,7 +200,7 @@ heroku login 1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - **Build Command:** `npm i -g pnpm@7 && pnpm docs:build` + - **Build Command:** `pnpm docs:build` - **Publish directory:** `docs/.vuepress/dist` 2. 设置 [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) 来选择 Node 版本： @@ -228,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)： From 4af2170a303ad4b7dae5f1aa1ae1d376dcefcba0 Mon Sep 17 00:00:00 2001 From: meteorlxy Date: Thu, 8 Dec 2022 21:18:10 +0800 Subject: [PATCH 13/13] chore: tweaks --- docs/README.md | 2 +- docs/guide/getting-started.md | 2 +- docs/zh/README.md | 10 +++++----- docs/zh/guide/bundler.md | 2 +- docs/zh/guide/getting-started.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index bf1228cc6f..d6919a4a0d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,7 +32,7 @@ footer: MIT Licensed | Copyright © 2018-present Evan You ```bash # install in your project -pnpm add -D vue @vuepress/client@next vuepress@next +pnpm add -D vuepress@next @vuepress/client@next vue # create a markdown file echo '# Hello VuePress' > README.md diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 36c065c7bc..67c62b1031 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -62,7 +62,7 @@ npm init ```bash -pnpm add -D vue @vuepress/client@next vuepress@next +pnpm add -D vuepress@next @vuepress/client@next vue ``` diff --git a/docs/zh/README.md b/docs/zh/README.md index 333986cb25..8e5618719f 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -31,16 +31,16 @@ footer: MIT Licensed | Copyright © 2018-present Evan You ```bash -# install in your project -pnpm add -D vue @vuepress/client@next vuepress@next +# 在你的项目中安装 +pnpm add -D vuepress@next @vuepress/client@next vue -# create a markdown file +# 新建一个 markdown 文件 echo '# Hello VuePress' > README.md -# start writing +# 开始写作 pnpm vuepress dev -# build to static files +# 构建静态文件 pnpm vuepress build ``` diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md index 2612f527ee..8579829d10 100644 --- a/docs/zh/guide/bundler.md +++ b/docs/zh/guide/bundler.md @@ -18,7 +18,7 @@ pnpm add -D vuepress-webpack@next - + ```bash yarn remove vuepress diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md index 924fef8aea..6b6a2c70be 100644 --- a/docs/zh/guide/getting-started.md +++ b/docs/zh/guide/getting-started.md @@ -60,10 +60,10 @@ npm init - **步骤 3**: 将 VuePress 安装为本地依赖 - + ```bash -pnpm add -D vuepress@next vue @vuepress/client@next +pnpm add -D vuepress@next @vuepress/client@next vue ```