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

secretFE

本文主要讲解的是用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文件，参考官网说明。

1. heroImage: /quistUI.png

复制代码

这个配置，需要在.vuepress文件夹下新建一个public文件夹，把图片放在这里，这样在打包的时候会自动打包。 2. 浏览器左侧的小图标 需要在config.js文件里进行配置，参考官网说明。 在我的项目里，和官网有一点点差别，href后的/。

1. #我的项目
2. head: [
3. ['link', { rel: 'icon', href: 'favicon.ico' }]
4. ]
5. #官网
6. head: [
7. ['link', { rel: 'icon', href: '/logo.png' }]
8. ]

复制代码

这两张图片都需要放在public文件夹下~ 首页上部导航 参考官网说明。 左侧导航 参考官网说明。 到这里，你的技术文档应该已经在本地可以浏览了，最后一步，部署。 部署 部署参考官网说明。

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

部署分为两步：

1. 在项目根目录下创建deploy.sh文件，与package.json是同级的。

1. #!/usr/bin/env sh
3. # 确保脚本抛出遇到的错误
4. set -e
6. # 生成静态文件
7. npm run docs:build
9. # 进入生成的文件夹
10. cd docs/.vuepress/dist
11. # git init 官网是有这行的，但我的项目里给注释掉了，因为我是现有项目，不想每次都初始化
13. # 下面这行是官网没有的，如果是多人开发项目，务必执行此命令
14. git pull [url]https://github.com/JDsecretFE/quist-ui.git[/url] master
15. git add -A
16. git commit -m 'deploy'
17. git push -f [url]https://github.com/JDsecretFE/quist-ui.git[/url] master:gh-pages
19. cd -

复制代码

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

1. "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鼓励一下~~~