使用VitePress可以让我们快速搭建一个静态博客网站，这篇文章将带领大家搭建一个基于VitePress的静态博客网站并且部署到GitHub Pages(github提供的静态网页服务)
快速上手
1. 新建目录并初始化(我的目录名为kittydocs)
这里我们使用pnpm式，当然yarn，npm都是可以的,如果你没有安装pnpm可以全局安装
然后初始化
2. 安装vitepress
3. package.json添加script
1
2
3
4
5
| "scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs"
}
|
这三个脚本分别代表启动本地文档服务，打包文档，启动打包后（dist）服务
4. 创建文档 文档放在docs目录下，新建docs/index.md
此时我们的文件结构为
1
2
3
4
| .
├─ docs
│ └─ index.md
└─ package.json
|
5. 启动本地服务文档站点
此时便会启动一个http://localhost:3000/ 的服务,默认加载docs/index.md
到这里一个简单的站点就完成了，当然这肯定是不够的，接下来我们看vitepress的配置
配置文件
在docs目录下创建一个 .vuepress目录，如下结构
1
2
3
4
5
6
| .
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ └─ index.md
└─ package.json
|
config.js导出一个js对象
1
2
3
4
| export default {
title: 'kittyui', //站点标题
description: '一个vue3组件库',//mate标签description，多用于搜索引擎抓取摘要
}
|
此时我们重启服务便可看到
导航栏
1. title和logo
首先看一下title和logo的配置
1
2
3
4
5
6
| export default {
themeConfig: {
siteTitle: "Kitty",
logo: "/logo.png",
},
};
|
其中logo的地址对应的是public下的图片，目录结构如下所示
1
2
3
4
5
6
7
8
| .
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ public
│ │ └─ logo.png
│ └─ index.md
└─ package.json
|
这里logo我是用了vue的图标，此时页面效果为
2. 右侧导航
我们可以在themeConfig.nav配置右侧导航,并且点击可以跳转我们指定页面。
1
2
3
4
5
6
7
8
9
| themeConfig: {
siteTitle: "Kitty",
logo: "/logo.png",
nav: [
{ text: "Guide", link: "/guide/" },
{ text: "GuideTest", link: "/guide/test" },
{ text: "gitee", link: "https://gitee.com/geeksdidi" },
],
}
|
同时我们在docs下新建guide/index.md和test.md
此时我们页面即可展示我们打nva并且支持了跳转本地markdown文件以及外部链接
我们还可以这样嵌套配置，使得导航栏出现下拉选项
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| themeConfig: {
siteTitle: "Kitty",
logo: "/logo.png",
nav: [
{ text: "Guide", link: "/guide/" },
{ text: "GuideTest", link: "/guide/test" },
{ text: "gitee", link: "https://gitee.com/geeksdidi" },
{
text: "Drop Menu",
items: [
{ text: 'Item A', link: '/item-1' },
{ text: 'Item B', link: '/item-2' },
{ text: 'Item C', link: '/item-3' }
]
}
]
}
|
如果我们想要让下拉选项分组，即中间有条分割线，我们的nav可以这样写
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| nav: [
{ text: "Guide", link: "/guide/" },
{ text: "GuideTest", link: "/guide/test" },
{ text: "gitee", link: "https://gitee.com/geeksdidi" },
{
text: "Drop Menu",
items: [
{
items: [
{ text: "Item A1", link: "/item-A1" },
{ text: "Item A2", link: "/item-A2" },
],
},
{
items: [
{ text: "Item B1", link: "/item-B1" },
{ text: "Item B2", link: "/item-B2" },
],
},
],
},
]
|
此时效果为
配置社交链接socialLinks
使用themeConfig.socialLinks可以配置我们的社交链接，目前支持的有
1
2
3
4
5
6
7
8
9
10
| type SocialLinkIcon =
| 'discord'
| 'facebook'
| 'github'
| 'instagram'
| 'linkedin'
| 'slack'
| 'twitter'
| 'youtube'
| { svg: string }
|
配置如下
1
2
3
4
5
6
7
8
9
10
11
| socialLinks: [
{ icon: "github", link: "https://gitee.com/geeksdidi" },
{ icon: "twitter", link: "..." },
// You can also add custom icons by passing SVG as string:
{
icon: {
svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>',
},
link: "...",
},
],
|
侧边栏可以在themeConfig.Sidebar中配置，其实和nav配置差不多
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| sidebar: [
{
text: "组件库源码实现",
items: [
{
text: "组件库环境搭建",
link: "/articles/组件库环境搭建",
},
{ text: "gulp的使用", link: "/articles/gulp的使用" },
],
},
{
text: "vue教程",
items: [
{
text: "pina和vuex",
link: "/articles/pina和vuex",
},
],
},
],
|
这里我搬运了我掘金上的一些文章放了进去，目录结构如下图
页面展示效果如下
不过我们一般不会使用这种方式配置侧边栏，因为这样每个页面都会有侧边栏。我们需要做到仅某些页面才会出现侧边栏。所以我们可以这样配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| sidebar: {
"/articles/": [
{
text: "组件库源码实现",
items: [
{
text: "组件库环境搭建",
link: "/articles/组件库环境搭建",
},
{ text: "gulp的使用", link: "/articles/gulp的使用" },
],
},
{
text: "vue教程",
items: [
{
text: "pina和vuex",
link: "/articles/pina和vuex",
},
],
},
],
},
|
sideBar值改成一个对象，对象的key是一个路径，只有包含这个路径的才会出现侧边栏。所以我们将nav的配置中的guild改成博客，同时路径指向我们的articles下的markdown文件
1
2
3
| nav: [
{ text: "博客", link: "/articles/组件库环境搭建" },
]
|
此时你会发现进入首页并不会出现sideBar，只有点击博客才会出现侧边栏
配置可折叠侧边栏
配置可折叠侧边栏只需将collapsible设置为true即可,默认初始页面是全部展开页面，如果你需要关闭状态只需要将collapsed设置为true
1
2
3
4
5
6
7
8
9
10
11
12
13
| ...
{
text: "vue教程",
collapsible: true,
collapsed:true,
items: [
{
text: "pina和vuex",
link: "/articles/pina和vuex",
},
],
},
...
|
首页布局
首页就是进入我们博客会加载docs/index.md,所以我们需要对其进行一个美化，我们VitePress默认主题提供了一个主页布局
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
| ---
layout: home
hero:
name: 东方小月的博客
text: 随便写点啥.
tagline: 帅气又迷人的小月
image:
src: /logo.png
alt: Kitty
actions:
- theme: brand
text: 快来快来
link: /articles/组件库环境搭建
- theme: alt
text: View on Gitee
link: https://gitee.com/geeksdidi
features:
- icon: ⚡️
title: 这是一个闪电图标
details: wawawa
- icon: 🖖
title: 这是一个手掌图标
details: good...
- icon: 🛠️
title: 这是一个修理图标
details: cocococo
---
|
部署到GitHub Pages
1. 新建github仓库
既然要部署到GitHub Pages，你得先在github新建一个仓库，因为要用他的GitHub Pages，所以仓库命名为username.github.io的形式，username是你github的用户名。然后点击设置
选择pages
这里设置根目录/(root),当然也可以选择其它目录,点击保存，如果选择其它目录比如docs，config.js就需要配置一个base
1
2
3
| export default {
base:'/docs/'
}
|
最后选择一个主题(这里不选择我发现站点不生效,后面把打包后的代码推上来即可,会默认加载index.html)
然后将打包后的dist下的文件推送到你的远程仓库。vitepress官网给我们提供了一个脚本文件deploy.sh，我们只需要改下远程仓库即可
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
| #!/usr/bin/env sh
# 忽略错误
set -e
# 构建
npm run docs:build
# 进入待发布的目录
cd docs/.vitepress/dist
# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
# 如果是部署到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
cd -
|
直接执行这个脚本文件，我们的打包后的文件就会被推送到我们的仓库。然后我们就可以直接访问我们的静态博客站点了，如果你想要自定义其它域名的话,可以创建一个组织然后在组织下新建仓库名为organization.github.io的形式(organization是你组织名)然后执行同样的操作即可。具体可以点这里创建 GitHub Pages 站点
3. 通过Windows系统下使用的脚本文件部署
上一步我们上传的仅仅是工程的源代码。还需要上传构建成果，才能发布博客网站。我们在工程根目录创建文件bin/autoDeploy.bat，这是一个Windows系统下使用的脚本文件。
1
2
3
4
5
6
7
8
| call pnpm docs:build
cd docs/.vitepress/dist
git init
git add -A
git commit -m "auto construct blog"
git push -f https://github.com/jzplp/jzplp.github.io.git master:gh-pages
|
注意里面的push地址需要改成你自己的。
文件内容即是我们的构建和发布流程： 1. 构建工程，生成dist，并进入dist目录。 2. 将dist目录中的内容上传至gh-pages分支中。
如果使用非Windows系统，对该脚本文件后缀名和内容进行适当修改即可。
我们在package.json的scripts中增加一条命令：
1
| "deploy:win": "powershell bin/autoDeploy.bat"
|
此时可以执行这条命令，即可完成dist构建包的上传。
4. 使用GitHub Actions进行自动构建和发布
使用上面描述的方法，我们每次写完博客，提交工程代码后，还需要手动构建，更新分支并发布。
那么有没有方法让每次提交工程代码后，自动构建并发布呢？我们使用GitHub Actions就能做到这一点。而且GitHub还提供了服务器，我们可以把构建过程放到服务器中进行。
首先创建配置文件，位置.github/workflows/deploy.yml。
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
| name: algolia
on:
push: # 有代码push或者merge到main分支时，才进行下面的操作
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Install Node.js
uses: actions/setup-node@v3
with:
node-version: 16
- uses: pnpm/action-setup@v2 # 配置使用pnpm
name: Install pnpm
id: pnpm-install
with:
version: 8
run_install: false
- name: Get pnpm store directory
id: pnpm-cache
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
- uses: actions/cache@v3
name: Setup pnpm cache
with:
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Install dependencies
run: pnpm install
- name: Build docs
run: pnpm run docs:build
- name: Deploy Files on Ftp Server
uses: SamKirkland/FTP-Deploy-Action@4.3.3
with:
server: '' # FTP服务器地址
username: '' # FTP用户名
password: '' # FTP密码
local-dir: ./docs/.vitepress/dist/ #需要发布内容的路径
server-dir: ./wwwroot/
protocol: ftp
port: 21
|
GitHub Actions的环境中提供了很多预置的配置和工具，例如Node.js，pnpm等等，我们直接使用即可。如果你的配置和文中上述流程一致，那么直接复制该文件内容到你的工程即可。之后上传到工程代码GitHub仓库中。如果想了解更多，可以参考GitHub Actions文档以及其他人的配置。
当然，你如果没有自己的FTP服务器，希望自动部署到Github Pages，配置方法参考：使用Github Action实现全自动部署