showdoc - 好用的个人/家庭/团队私有化知识库管理搭建指南教程

嘿，这里是「青柠炸机店」，本篇文章是知识库软件工具的系列教程之一，本系列涉及的知识库软件，见这篇文章！

📡 安装部署

部署机器使用极空间 Z4 pro

• 第一步：镜像选择 star7th/showdoc

• 第二步：配置端口和文件映射

• 第三步：运行镜像

• 第四部：登录showdoc文档管理系统

启动镜像后，浏览器访问showdoc页面，选择完成语言后，会给一个默认用户名和密码，登录进去后记得修改哈！

最新版本支持 - 项目列表卡片视图和列表视图切换了。之前的列表布局，真的一言难尽，看不习惯。

在 技术团队文档示例 中，可以查看 markdown语法和plantuml语法，以及一些🌰例子，可以作为文档的参考。

🧭 使用指南

知识库核心三要素：人员、项目、文档。他们三个的关系如下图所示

团队管理

可以进行以团队为单位的管理，每个团队有不同的文档权限，互不干扰！同时一个用户也可以在某几个团队中任职，管理多个团队的文档数据。

项目管理

将文档以项目的形式进行管理，每个项目可以分配给不用的团队

新建项目

项目管理

文档管理

在 Showdoc 中，项目包含并组织多个文档，文档从属于特定项目。

文档主要以 markdown 为主，也可以创建Excel表格，同时还支持plantuml，包括时序图、用例图、类图、组件图、状态图等等。

搭建好后，首先需要创建一个项目，在项目中，新建文档。如果不熟悉markdown语法和plantuml语法，可以在 技术团队文档示例 中，可以看到很多文档的例子，照着看一些就学会了，很简单的！

这里讲解一个使用代码，生成开发文档的例子🌰：

API 文档生成

文档直达链接

• showdoc 官方提供了一种自动化生成接口和文档的方案。在代码里编写特定格式的程序注释，然后程序就可以通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可以支持`c++`、`java`、`php`、`node` 等等常见的主流语言。

• 采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录 showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写接口和文档”这件事如”单元测试”般纳入工程工作流里面。

以 windows 下的操作为例

注意：📣windows无法直接运行sh脚本，需要额外下载软件。

1. 下载 git for windows；

2. 下载**showdoc**官方脚本；

3. 将`showdoc_api.sh`放在项目目录下，编辑脚本中的`api_key` 和 api_token，如果自建服务，再编辑一下`url地址`；

4. 搞定上面3项后，然后直接双击运行，脚本会自动递归本目录和子目录的所有文本代码文件，生成的文档会放进 api_key 所指向的这个项目里。

==注意：代码注释要使用 showdoc 规范==

/** * showdoc * @catalog 测试文档/用户相关 * @title 用户登录 * @description 用户登录的接口 * @method get * @url https://www.showdoc.cc/home/user/login * @header token 可选 string 设备token * @param username 必选 string 用户名 * @param password 必选 string 密码 * @param name 可选 string 用户昵称 * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}} * @return_param groupid int 用户组id * @return_param name string 用户昵称 * @remark 这里是备注信息 * @number 99 */

后台管理

后台管理可以对 人员、项目、附件、站点进行管理和配置

♾️ 其它功能

数据字典生成

文档直达链接

和生成API类似，需要先下载指定脚本文件，之后修改配置信息，最后执行脚本命令！

链接分享

可以将单篇文章或者笔记以链接的形式分享给客户，非常方便：

自动更新

不像其它很多应用，需要使用手动更新方式，showdoc它可以一键更新镜像，这点非常方便，值得点赞👍！

免费 OR 付费

接下来本系列教程还有：

• 「MrDoc 安装与使用指南 」

• 「zyplayer 安装与使用指南 」

• 「docmost 安装与使用指南 」

• 「outline 安装与使用指南 」

知识库管理工具[zyplayerdoc/MrDoc/showdoc/outline/docmost] 对这几款软件进行详细的介绍 📝，其中包括界面操作 🖥️、部署方式 🌐、主要功能 🔧，看完这几篇文章，我相信你一定会找到适合自己的知识库软件的。如果你对私有化部署知识库感兴趣 🤓，三连支持一下 👍👍👍，关注我接下来的更新吧！🔔

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～