部署基于 VuePress 框架的 Wiki 文档

部署基于 VuePress 框架的 Wiki 文档

VuePress 是由 Vue.js 核心团队维护的静态网站生成器。它专为技术文档设计而生，尤其适合 Vue 项目文档，也可以部署为 blog 模式

VuePress 默认主题比较简陋，功能不够强大，需要手动安装一系列依赖包并在主配置文件中设置，对小白并不友好

vuepress-theme-hope 主题则在默认主题基础上集成了一系列增强组件和插件，并将配置集中在 src/.vuepress/theme.ts 文件中

技术栈

简易部署说明

前置条件

  • 安装 vscode
  • 安装 node.js
  • 安装 pnpm
1
npm install -g pnpm

创建项目

1
pnpm create vuepress-theme-hope <替换为你的文件夹名>

安装依赖包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# algolia 搜索
pnpm add -D @vuepress/plugin-docsearch@next
# 本地搜索
pnpm add -D @vuepress/plugin-search@next
# rss
pnpm add -D @vuepress/plugin-feed@next
# pwa 支持
pnpm add -D @vuepress/plugin-pwa@next
# waline 评论
pnpm add -D @waline/client@next
# 阅读时间字数
pnpm add -D @vuepress/plugin-reading-time@next
# 幻灯片支持
pnpm add -D @vuepress/plugin-revealjs@next
# 代码块语法高亮
pnpm add -D @vuepress/plugin-prismjs@next
# artplayer 播放器
pnpm add -D artplayer@next
# vidstack 播放器，支持音频、视频、直播
pnpm add -D vidstack@next

卸载依赖包

1
pnpm remove <需要卸载的包名>

清理未使用的包

1
pnpm prune

更新依赖库

1
2
3
4
# 安装 package.json 中声明的依赖
pnpm install
# 更新依赖到最新版
pnpm update

升级 Vuepress 框架和 Vuepress-theme-hope 主题

1
pnpm dlx vp-update  升级

本地预览与构建

1
2
3
4
5
6
# 本地预览
pnpm docs:dev
# 本地构建输出静态页面，路径：src/.vuepress/dist
pnpm docs:build
# 清除缓存并本地预览
pnpm docs:clean-dev

部署到 CF Pages

  • 构建命令：pnpm docs:build
  • 输出目录：src/.vuepress/dist
  • 点击部署
  • 绑定自定义域名

项目配置说明

配置文件路径

1
2
3
4
5
6
7
8
// vuepress 主配置文件
src/.vuepress/config.ts
// VuePress Theme Hope 主题配置文件
src/.vuepress/config.ts/theme.ts
// 顶部导航栏配置文件
src/.vuepress/config.ts/navbar.ts
// 侧边栏配置文件
src/.vuepress/config.ts/sidebar.ts

关于 VuePress Theme Hope 主题

VuePress 默认主题配置文件为 src/.vuepress/config.ts，默认主题比较简陋，功能不够强大，需要手动安装一系列依赖包并在主配置文件中设置。

vuepress-theme-hope 主题则在默认主题基础上集成了一系列增强组件和插件，并将配置集中在 src/.vuepress/theme.ts 文件中

配置示例

优化整理的配置文档

使用文档

发布文章

创建 MD 文档

在 /src 目录下创建 wiki 知识库文件夹，并与，并在 navbar.ts 和 sidebar.ts 做好对应的目录设置，然后在文件夹下创建 md 文档

目录结构示意：

1
2
3
4
5
6
7
8
9
10
11
12
13
/src
├── 文件夹1
│   ├── 文档1.md
│   ├── 文档2.md
│   └── 文档3.md
├── 文件夹2
│   ├── 文档1.md
│   ├── 文档2.md
│   └── 文档3.md
├── 文件夹3
    ├── 文档1.md
    ├── 文档2.md
    └── 文档3.md

发布文档

通过 vscode 将本地更改推送到自己的 github，CF pages 会自动部署

访问 CF pages 绑定的自定义域名即可

#建站 #文档 #cloudflare #github