前言

知识库与博客文章结构不同，各有优势，于是尝试搭建一个文档知识库。

搭建环境：

  • Node 20.18.0
  • npm 10.8.2
  • github pages

1 创建仓库

1.1 github建仓

在github里new一个repository

clone到本地

1
git clone <>

进入到clone的文件夹里，在文件夹处打开cmd或powershell

1.2 初始化vitepress

1
npx vitepress init

输入示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

T  Welcome to VitePress!
|
o  Where should VitePress initialize the config?
|  ./docs
|
o  Site title:
|  Eason815的文档站
|
o  Site description:
|  好记性不如烂笔头
|
o  Theme:
|  Default Theme
|
o  Use TypeScript for config and theme files?
|  No
|
o  Add VitePress npm scripts to package.json?
|  Yes
|
—  Done! Now run npm run docs:dev and start writing.

Tips:
- Make sure to add  docs/.vitepress/dist and  docs/.vitepress/cache to your .gitignore file.

可以使用文本编辑器如Vscode打开本地文件夹

1.3 测试启动

在文件夹里安装依赖

1
npm add -D vitepress

启动 (具有即时热更新的本地开发服务器)

1
npm run docs:dev

2 部署

2.1 push仓库

在项目文件夹根目录下

创建文件.gitignore

1
2
3
4
5
6
7
8
node_modules
.DS_Store
dist
dist-ssr
cache
.cache
.temp
*.local

推送远端

1
2
3
git add .
git commit -m "init"
git push -u origin main

2.2 设置为工作流

到github查看是否推送成功

导航栏选择Settings,点击菜单项Pages，在Build and deployment > Source 下拉栏中选择 GitHub Actions

2.3 创建工作流文件并启用

导航栏选择Actions,点击set up a workflow yourself

也可以选择本地文件夹创建, 这里在github里进行创建

  1. 文件名命名为deploy.yml
  2. 根据需求修改后 粘贴下方代码
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    # 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
    #
    name: Deploy VitePress site to Pages

    on:
      # 在针对 `main` 分支的推送上运行。如果你
      # 使用 `master` 分支作为默认分支，请将其更改为 `master`
      push:
        branches: [main]

      # 允许你从 Actions 选项卡手动运行此工作流程
      workflow_dispatch:

    # 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
    permissions:
      contents: read
      pages: write
      id-token: write

    # 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
    # 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
    concurrency:
      group: pages
      cancel-in-progress: false

    jobs:
      # 构建工作
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v4
            with:
              fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
          # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
          # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
          - name: Setup Node
            uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: npm # 或 pnpm / yarn
          - name: Setup Pages
            uses: actions/configure-pages@v4
          - name: Install dependencies
            run: npm ci # 或 pnpm install / yarn install / bun install
          - name: Build with VitePress
            run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
          - name: Upload artifact
            uses: actions/upload-pages-artifact@v3
            with:
              path: docs/.vitepress/dist

      # 部署工作
      deploy:
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        needs: build
        runs-on: ubuntu-latest
        name: Deploy
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
  3. 点击Commmit changes...

再次回到Settings > Pages可以看到网页已经部署

2.4 修补css样式丢失

回到文件夹记得拉一下

1
git pull

若发现打开页面丢失css样式

在项目文件夹根目录下的docs文件夹 (看自行设置情况)

创建空文件.nojekyll即可

2.5 修补base

在项目文件夹根目录下的docs文件夹 (看自行设置情况)

找到.vitepress里的config.mjs文件

添加base为项目名称

1
2
3
4
5
6
7
8
9
10
11
12
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index 5e1e098..6844834 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitepress'

 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  base: "/docs/",
   title: "Eason815的文档站",
   description: "好记性不如烂笔头",
   themeConfig: {

2.6 更新部署

之前使用过git push -u origin main

-u是--set-upstream的简写

即将本地的 main 分支与远程的 origin/main 分支关联起来

后续的 git push 和 git pull 操作中，可以直接使用 git push 或 git pull 而不需要每次都指定远程分支

1
2
3
git add.
git commit -m "fix"
git push

再次回到Settings > Pages可以看到网页已经部署

应该是没有问题了

3 维护

3.1 本地测试

1
npm run docs:dev

3.2 重新部署

1
2
3
git add.
git commit -m "fix"
git push

参考

https://docs.bugdesigner.cn/docs/Tutorial/vitepress.html