vuepress搭建技术文档实战（带github项目地址）

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

最终效果如下图：

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

重要提示

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

背景

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

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

开始

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

目录结构

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

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

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

heroImage: /quistUI.png
复制代码

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

2. 浏览器左侧的小图标

需要在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"
复制代码

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

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

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

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

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

转载于:https://juejin.im/post/5bc47a3fe51d450e5a746390