vuepress搭建技术文档实战(带github项目地址)

时间:2024-03-25 21:36:31

本文主要讲解的是用vuepress搭建一个技术文档,且这个技术文档是与github pages 相关联的。就是我们常见的下图的这种:

vuepress搭建技术文档实战(带github项目地址)

 

最终效果如下图:

vuepress搭建技术文档实战(带github项目地址)

 

如果与你想要做的一样,请仔细阅读下面的内容。

重要提示

本文不会重复介绍官方文档的内容,官网的API已经写得很详细并且写得很好了。所以,请先按照官网的讲解一步步实践,如果遇到其他的问题,这篇文章的内容也许能够帮到你。去官网

 

背景

一开始我并不是想直接搭建一个技术文档,我们团队是先开发了一套快应用UI组件库Quist-UI,为了方便开发者阅读,最后决定用vuepress搭建。所以,我用的安装方式和官网介绍的现有项目安装是一致的。

 

我的项目一开始就是快应用的一个项目架构,webpack的版本是3.12.0。

 

开始

在用现有项目安装时,我遇到了一个怪异的问题,执行npx vuepress dev docs的命令时,总是报错。如果你也遇到了,试试全局安装yarn global add vuepressnpm install -g vuepress

 

目录结构

vuepress搭建技术文档实战(带github项目地址)

 

有两点要特殊说明一下,当时我在配置的时候也费了点时间。

1. 首页的图片(在这里就是白色鸽子的那张图)

打开docs文件夹下的README.md文件,参考官网说明

heroImage: /quistUI.png

这个配置,需要在.vuepress文件夹下新建一个public文件夹,把图片放在这里,这样在打包的时候会自动打包。

2. 浏览器左侧的小图标

vuepress搭建技术文档实战(带github项目地址)

需要在config.js文件里进行配置,参考官网说明。在我的项目里,和官网有一点点差别,href后的/。

#我的项目
head: [
    ['link', { rel: 'icon', href: 'favicon.ico' }]
]
#官网
head: [
    ['link', { rel: 'icon', href: '/logo.png' }]
]

这两张图片都需要放在public文件夹下~

 

首页上部导航

参考官网说明

 

左侧导航

参考官网说明

 

到这里,你的技术文档应该已经在本地可以浏览了,最后一步,部署。

 

部署

参考官网说明

上面说过,我的项目是部署github上的,所以,这里只说github的部署方式,且只说和官网哪些地方是不同的。

部署分为两步:

  1. 在项目根目录下创建deploy.sh文件,与package.json是同级的。
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist
# git init 官网是有这行的,但我的项目里给注释掉了,因为我是现有项目,不想每次都初始化

# 下面这行是官网没有的,如果是多人开发项目,务必执行此命令
git pull https://github.com/JDsecretFE/quist-ui.git master 
git add -A
git commit -m 'deploy'
git push -f https://github.com/JDsecretFE/quist-ui.git master:gh-pages

cd -

 

打开package.json文件,添加scripts的命令,如下图:

"deploy": "bash deploy.sh"

vuepress搭建技术文档实战(带github项目地址)

    2. 登录github,找到settings->GitHub Pages,选择gh-pages分支,保存。

vuepress搭建技术文档实战(带github项目地址)

 

vuepress搭建技术文档实战(带github项目地址)

 

现在我们打开命令工具,查看我们的分支,应该有一个master分支和gh-pages分支(如果没有gh-pages分支,自行创建一个)。我们在master分支上执行 npm run deploy命令,这时docs/.vuepress下会多出一个dist文件夹,我们要的东西都在这里了。

 

vuepress搭建技术文档实战(带github项目地址)

 

最后,我们把master分支下dist文件夹里的内容拷贝到gh-pages分支,完成。

 

如果你有更好的方式,也请回复我一下,感谢感谢。

最后附上项目地址,请参考此项目下的docs项目结构。如果帮助到你,请给个star鼓励一下~~~