基于VuePress快速搭建一套项目知识管理工具

用互联网思维来看知识管理工具

阅读全文需15分钟，动手实践需30分钟，欢迎点赞收藏。

线上演示地址：http://39.106.163.86:8081/

GitHub地址：https://github.com/chenshuaikang/ShareDoc

用户背景

我是一名开发人员，经常会迷失在寻找团队内的各种开发文档中，我期望有一个网站，所有文档都集中在这个网站中，我可以进行根据目录浏览，最好能支持搜索，而且我贡献的文档别人不知道，会再跑过来问我。

用户痛点

• 文档存放位置杂乱
• 搜索文档困难
• 文档没有目录
• 文档普及度不高

工具选型

团队文档知识管理工具有很多，很多大厂出了软件专门来做知识管理，比如xx笔记企业版，这些大厂的软件必须购买企业版才能在团队内共享，且笔记很杂，不利于管理。而且根本就没有解决用户痛点。

最后选择了vuePress来做，它的好处是可以用markdown语言来做笔记，让你专注于写作，还可以将笔记提交到gitlab进行管理，还有变更记录，而且高度支持自定义主题等等。

于是我们选择了vuepress。官网链接：https://v0.vuepress.vuejs.org/zh/

官网也是用VuePress做的哦。但这个开源工具不是下载下来就可以直接用的，还有些开发工作需要做。

VuePress有以下特性（来自官网）：

1. 为技术文档而优化的 内置 Markdown 拓展
2. 在 Markdown 文件中使用 Vue 组件的能力
3. Vue 驱动的自定义主题系统
4. 自动生成 Service Worker
5. Google Analytics 集成
6. 基于 Git 的 “最后更新时间”
7. 多语言支持
8. 默认主题包含： - 响应式布局 - 可选的主页 - 简洁的开箱即用的标题搜索 - Algolia 搜索 - 可自定义的导航栏 和侧边栏 - 自动生成的 GitHub 链接和页面的编辑链接搭建此工具按照官网搭建、

注意

请确保你的 Node.js 版本 >= 8

全局安装

如果你只是想尝试一下 VuePress，你可以全局安装它：

# 安装
yarn global add vuepress # 或者：npm install -g vuepress

# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

现有项目中使用

如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。

# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress # 或者：npm install -D vuepress

# 新建一个 docs 文件夹
mkdir docs

# 新建一个 markdown 文件
echo '# Hello VuePress!' > docs/README.md

# 开始写作
npx vuepress dev docs

注意

如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。

接着，在 package.json 里加一些脚本:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

然后就可以开始写作了:

yarn docs:dev # 或者：npm run docs:dev

要生成静态的 HTML 文件，运行：

yarn docs:build # 或者：npm run docs:build

默认情况下，文件将会被生成在 .vuepress/dist，当然，你也可以通过 .vuepress/config.js 中的 dest 字段来修改，生成的文件可以部署到任意的静态文件服务器上。

这些步骤执行完后，只能看到搜索栏和标题，是没有菜单的，需要自己创建菜单。

使用模板demo搭建

创建菜单

上面只有搜索功能，没有菜单功能。修改config文件定义菜单，然后加上菜单对应的文件夹。

使用模板demo

我已经有一份做好的demo供大家使用，该demo的功能：展示接口文档，供第三方使用。功能如下图：

GitHub地址：https://github.com/chenshuaikang/ShareDoc

编写文档

比如想增加一个更新会员信息的接口，可以在member目录下面创建一个update.md文件

然后在config.js 文件配置菜单

编译运行

如果已经安装了node.js和npm，则在该项目的根目录执行这条命令就可以运行起来了

npm start

这条命令其实就是执行npm vuepress dev来进行实时编译

编译完成后，会提示监听8080端口，可以打开http://localhost:8080查看效果

部署到服务器

将项目打包成静态文件

npm run build

将生成的静态文件（public文件夹）上传至服务器

我是部署到ubuntu上的，需要配置nginx（也可部署Tomcat等容器中）

# nginx配置
server {
    listen       8081;
    server_name  localhost;
 
    location / {
        # 项目所在目录
        root   /home/ShareDoc/public;
        index  index.html index.htm;
        try_files $uri $uri/ =404;
    }
}

访问项目站点：

http://39.106.163.86:8081/