详解如何搭建一套知识管理工具

阅读目录

1、用互联网思惟来看知识管理工具

2、工具选型

3、开始搭建这套工具

4、如何编译运行

5、如何部署到服务器

6、如何自动部署到云服务器

Github连接：

https://github.com/Jackson0714/BirdDoc   记得点个Star

1、用互联网思惟来看知识管理工具

1.1 用户故事

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

1.2 用户痛点

（1）文档存放位置杂乱

（2）搜索文档困难

（3）文档没有目录

（4）文档普及度不高

1.3 产品团队深挖用户痛点

根据用户的痛点，产品团队设计了一个模型

（1）左侧具备菜单导航栏

（2）顶部具备搜索栏

（3）能够经过网站的形式访问，方便用户访问

2、工具选型

这种团队管理工具备不少，不少大厂出了软件专门来作知识管理：

好比xx笔记企业版

这些大厂的软件必须购买企业版才能在团队内共享，且笔记很杂，不利于管理。并且根本就没有解决用户痛点。

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

因而咱们选择了vuepress。官网连接：https://v0.vuepress.vuejs.org/zh/

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

另外有人提出怎么不用GitBook ？

 GitBook 最大的问题在于当文件不少时，每次编辑后的从新加载时间长得使人没法忍受。它的默认主题导航结构也比较有限制性，而且，主题系统也不是 Vue 驱动的。GitBook 背后的团队现在也更专一于将其打造为一个商业产品而不是开源工具。 -- 来源vuepress

3、开始搭建这套工具

3.1 方案一 按照官网搭建

快速上手

注意

请确保你的 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 

WARNING

若是你的现有项目依赖了 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 字段来修改，生成的文件能够部署到任意的静态文件服务器上，参考 部署 来了解更多。

这些步骤执行完后，只能看到搜索栏和标题，是没有菜单的，须要本身建立菜单。

3.2 方案2、用个人demo搭建

3.2.2 如何建立菜单

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

3.2.2 下载demo

我已经有一份作好的demo供你们使用，该demo的功能：展现接口文档，供第三方使用。功能以下图。

github路径：https://github.com/Jackson0714/BirdDoc

 

3.3.3 如何编写文档

好比想增长一个删除优惠券的接口，能够在coupon目录下面建立一个delete.md文件

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

4、如何编译运行

若是已经安装了node.js和npm，则在根目录执行这条命令就能够运行起来了

1

npm start

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

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

 

5、如何部署到服务器

5.1 打包成静态文件

npm run build

5.2 配置nginx和hosts

我是部署到ubuntu上的，须要建立nginx 配置文件

// 建立nginx配置文件<br>sudo vim /etc/nginx/conf.d/interface.conf // interface.conf server {      listen       8002;      server_name  birddoc.com;        location / {          root   /home/user/project/github/BirdDoc/public;          index  index.html index.htm;          try_files $uri $uri/ =404;      } } // 重启nginx服务 sudo service nginx restart // 配置hosts文件，映射网站域名 sudo vim /etc/hosts localhost birddoc.com

5.3 打开站点

http://birddoc.com:8002/

6、如何自动部署到云服务器

6.1 拉取代码

git clone git@github.com:Jackson0714/BirdDoc.git

6.2 打包镜像文件

npm run build<br><br>> kidsplace- interface @1.0.0 build /home/workspace/BirdDoc/BirdDoc > vuepress build       WAIT  Extracting site metadata... [9:59:39 AM] Compiling Client [9:59:39 AM] Compiling Server [9:59:45 AM] Compiled Server  in  6s [9:59:51 AM] Compiled Client  in  13s   WAIT  Rendering  static  HTML...     DONE  Success! Generated  static  files  in  public.<br><br>

生成静态文件，路径为 /home/workspace/BirdDoc/BirdDoc/public

6.3 添加域名解析

在云服务器控制台 添加 birddoc.jay.club的域名解析，网站jay.club是我本身备案的网站。

等待10分钟就生效了。

6.4 修改nginx配置文件

监听经过birddoc.jay.club发来的请求，路由到静态文件目录 /home/workspace/BirdDoc/BirdDoc/public

server {      listen       80;      server_name  birddoc.jayh.club;        location / {          root   /home/workspace/BirdDoc/BirdDoc/public;          index  index.html index.htm;          try_files $uri $uri/ =404;      } }

 6.5 打开网站

http://birddoc.jayh.club

 

（临时网站，后面可能会停掉。）

 6.6 如何用jenkins部署

参考我以前写的文章：1. 容器化部署一套云服务 第一讲 Jenkins（Docker + Jenkins + Yii2 + 云服务器)）

最后部署成功，控制台输出以下图：

 

 

查看public目录下这些文件

 6.7 如何自动部署

自动部署的方式不少

6.7.1 Jenkins 定时构建

6.7.2 Crontab定时构建

注意：该脚本还有些编译问题未解决，仅供参考。

/home/job/build.sh   #!/bin/bash cd /home/workspace/BirdDoc/BirdDoc /usr/bin/git pull /usr/local/n/versions/node/10.15.3/bin/npm run build currentTime=$(date) echo $currentTime >> /home/job/build.log   crontab -e * * * * * sleep 0; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 5; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 10; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 15; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 20; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 25; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 30; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 35; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 40; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 45; /home/job/build.sh >> /home/job/cron.log 2>&1 & * * * * * sleep 55; /home/job/build.sh >> /home/job/cron.log 2>&1 &

6.7.3 Jenkins经过git提交代码触发构建

我配置了GitHub hook trigger for GITScm polling，但仍是没有自动触发。

后续再用docker run起来。

本文分享自微信公众号 - 悟空聊架构（PassJava666）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。