记录vitepress搭建的文档部署到Github

最近使用vitepress搭建了一个项目，该项目主要记录平时开发中遇到的琐碎知识点，以及如何部署到github上，可以随时查看。

全文主要分为两大模块：

1、使用vitepress开发

1.1 初始化项目

npm init

1.2 项目初始化完成之后，安装vitepress依赖。

npm i vitepress -D

1.3 配置项目目录结构

创建docs/.vitepress的目录和配置文件、首页、public。

├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ └─ index.md
│ └─ public
└─ package.json

目录说明：
docs/.vitepress：用于存放全局的配置、自定义组件、自定义主题等。
config.js:项目配置文件
public:公共文件目录，存放静态资源。
index.md：项目的首页

config.js文件中有个重要的配置：
base: "blog",
这个blog就是我们的仓库名称，为什么要和仓库名称一致，就是在打包后部署时可以直接获取到静态资源

1.4 配置运行脚本

  "script": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }

1.5 本地运行

npm run docs:dev

1.6 文档内容编写

此部分不做详细说明，主要是配置顶部导航和左侧菜单栏，文章文件名称和菜单栏配置文件名称一一对应，具体可以在网上搜索。

2、部署到github

此部分是本文的重点，之前在网上看了好几篇文章都没有顺利发布，经过九九八十一遍发布终于成功，特此记录。

网上关于部署到github有两种方案，一种是建立两个仓库，一个存放源码，一个存放打包后的代码，部署成功后用的是存放打包的仓库名称。另一种方案是同一个仓库，用不同的分支存放不同的代码，本文使用的是第二种方案。

2.1 创建仓库

在部署前，需要创建一个仓库，暂时命名为blog，仓库一定要设置为public，建立master分支，将之前已经写好的文档项目推送到master分支。

2.2 创建deploy.sh

#!/usr/bin/env sh
 
# 忽略错误
set -e  #有错误抛出错误
 
# 构建
npm run docs:build  #然后执行打包命令
 
# 进入待发布的目录
cd docs/.vitepress/dist  #进到dist目录
 
git init  #执行这些git命令
git add -A
git commit -m 'deploy'
 
git push -f https://github.com/xxx/blog.git master:gh-pages  #提交到这个分支
 
cd -
 
rm -rf docs/.vitepress/dist  #删除dist文件夹

这块要注意的是：git push的代码是存放在gh-pages分支的，所以我们的源码是在master分支，打包后的代码在gh-pages分支。

并且在package.json中添加配置行

  "script": {
    "deploy": "bash deploy.sh",
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }

2.3 github配置

在该目录下，找到setting，左侧找到pages。
打码的地方未配置前是没有的，所以直接看下边的build and deployment部分，可以看到选择分支，这时我们选择gh-pages，因为打包后的代码放在该分支，第二个按钮有root和docs两个选项，对应简单的项目，我们可以将项目首页index.html放在根目录下，如果跟目录没有index.html，则会将README.md解析成首页。所以这块我们选择root，然后点击save按钮。

2.4 执行npm run deploy

打包完成后刷新github仓库地址，然后在刚才配置的地方就可以看到生成的链接了，我们直接打开链接就可以看到自己的项目了。

到此，我们从创建项目、创建仓库到打包部署已经完成了，至于出现的样式混乱问题，就是因为配置时仓库名称和base配置不一致导致静态文件没有请求到导致的。