ShowDoc v3.0 发布 , 提升了产品颜值和操作体验，但是设计师说——

[star7th]

地址

开源地址： https://github.com/star7th/showdoc

官网： https://www.showdoc.com.cn/

开发小故事

在年前，设计师基本为 showdoc 设计出了一套 ui 主题。然而直到昨天，我才按设计稿重构了一版 UI 。虽然外观看着变化也不算非常大，但实际上底层代码已重构掉了一半，很多产品逻辑导致的底层组件封装方式发生了变化，同时我也借此机会修复了历史上不少代码的遗留包袱。

到现在，完成度还没有很高，很多细节没打磨好，大约只达到设计稿原意的六七成。我决定直接先发布一个 3.0 版，后面的问题后面完善。

设计师说，我习惯一步到位，做完善了再上。

我跟他就这个观点进行了交流，还蛮有意思的。这是两种风格迥异的产品思维。一种是把产品打磨得很好，一出场就惊艳用户。一种是小步快走，分阶段迭代。实际上，我也看过设计师的其他作品，确实给人的第一感觉就很惊艳，其产品给目标用户的第一印象非常好。

对于我的项目而言，我要照顾到开发时间成本和宣发机会，我比较愿意追求留给用户一种 “这个产品一直在优化在进步”的印象，而不需花太长的时间“憋大招”来惊艳用户。

尽管这个观点不同，但是我非常欣赏设计师的产品思维和对细节的追求。后续也继续有意愿跟他合作其他产品。

3.0 版本更新了什么

重写了 UI 和交互逻辑，大大提升了视觉效果和操作体验，包括但不限于以下内容：

• 展示多个项目时候采用列表结构，同时完善项目分组功能，适合更多项目的场景
• 大部分打开新页面的操作，如用户中心、目录管理、团队管理等等，都改为当前页面弹窗的形式，方便关闭弹窗后无感回到之前的操作，避免割裂感。
• 完善拖放组件，涉及到拖放的场景，比如项目分组的拖放、页面排序的拖放、目录管理的拖放，都统一元素高度和样式。
• 调整项目展示页的布局，包括常规多页项目、单页项目和表格展示项目，增加统一的 header 和图标样式。
• 调整功能按钮的展示与收起逻辑，在便捷和简洁间取得平衡。

给新用户看的 showdoc 介绍

ShowDoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具，既有开箱即用的在线托管服务版，也有免费的开源版( github 1 万+ star )。通过 showdoc ，你可以方便地使用 markdown 语法来书写出美观的 API 文档、数据字典文档、技术文档、在线 excel 文档等等。如果不想编辑 markdown 文档，你还可以利用 showdoc 的自动化能力，从程序注释中自动生成 API 文档，或者从搭配的 RunApi 客户端（类似 postman 的 api 调试工具）中一边调试接口、一边自动生成文档。无需手动编写文档，释放生产力。通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。ShowDoc 还支持多平台客户端，有 win 客户端、mac 客户端、ios 、android 等，更方便跨平台使用。目前超过 100000+的互联网团队正在使用 showdoc ，包括知名公司内部的一些团队，比如腾讯、华为、百度、京东、字节跳动等等。

关于 Showdoc 的详细介绍，请看： https://www.showdoc.com.cn/help

相关截图

[ieliwb]

正在用，支持

[highf4324]

很不错，不过还是建议首页左上角的 LOGO 不要用 PNG/JPEG 图像，因为看起来有点模糊。
建议直接用 svg ，这样无论怎样都不会模糊。

[yushiro]

showdoc 是换域名了吗？用之前保存的 url 都没法正常显示了

[superliwei]

👍 非常棒～！

[star7th]

@highf4324 主要是因为当初这个原始 logo 我没有保存源文件。只有一张大图。不过我倒可以使用大图生成各种分辨率的。所以你说的模糊问题，我尝试换个大分辨率一点的图标

[star7th]

@yushiro showdoc 官网域名是 https://www.showdoc.com.cn/ ，我不清楚你以前是否使用了非官方平台（即别人搭建开源版给他自己用的，而你跑去注册账号了）

[akiyamamio]

开源版和商业版有啥区别？

[star7th]

@superliwei
@ieliwb
谢谢支持

[star7th]

@akiyamamio 软件功能上的区别很小，可以忽略。

商业版主要是方便一些不想动手搭建的用户，更重要的是他们觉得数据交给 showdoc 官方去维护，比自己搭建的更可靠。尤其企业用户对数据的稳定性要求更高。如果是私自搭建开源版，服务器运维要你自己去保证可靠性。

[yushiro]

并不是用的其他人的，域名就是 showdoc.com.cn ，现在访问还是有问题，会去链接 dyfun-spare2.showdoc.这 com.cn:8888 这个地址，返回全部超时

[polarbearn]

从文档跳转到登录界面,会造成页面假死
刚刚提的 issues
github.com/star7th/showdoc/issues/1851

[EngAPI]

用了你们推送半年多，感谢

[mydingyan]

刚使用./showdoc update 命令升级了， 发现数据都被清空了， 应该怎么操作下

[star7th]

@yushiro

dyfun-spare2.showdoc 是我们自建的 cdn 服务，你那边访问有问题吗？
你是什么网络？如果是使用公司网络，会不会是公司安全限制了 8888 端口出口？能否用手机网络试一下？

[star7th]

@rolitter 好的，晚点修复下。

[star7th]

@EngAPI 多谢支持

[star7th]

@mydingyan
可能是没有写入权限导致。在你目录 /showdoc_data 下应该能找到类似 html_bakxxxx 这样名字的文件夹。将它改掉，替换原来的 html 目录，然后重启下 docker 容器就好了

[lower]

刚试了一下，8 年前的账号还能登录进去，当年的项目文档居然还都在😂

[pengtdyd]

好奇，showdoc 开源项目商业化能赚到钱吗？本身就是很小众的产品

[star7th]

@lower 嗯，多年来的账号没清理过。顶多清理下系统生成的示例文档, 但用户创建的数据没动。

[star7th]

@pengtdyd

能的。其实 api 以及文档市场没有你想象中的小众。甚至说这个领域并不小众，只是说我占据的市场份额小。

[mydingyan]

@star7th
感谢，使用上述方法覆盖后重新升级正常。UI 变化挺大，体验下~

[yushiro]

嗯，在 ping.sx 上看了一下，这个域名+端口，国外访问国内全部 timeout ，只能国内访问。
公司出口正好是 hk 的……

[star7th]

@yushiro

额。那应该是我们的 ip 库定位有差异。如果是非中国的 ip ，我们会转向国外节点。你这样，你用个代理先临时访问，用大陆内或者美国代理都行，我们后面修正下对香港的 ip 库记录。

[Psily1017]

支持，刚毕业就接触到 showdoc ，从 1.0 用到了 3.0 ，肉眼可见的 ui 设计变得越来越漂亮和功能逻辑变得实用。

[star7th]

@Psily1017

1.0 的版本，那确实有好几年了。

[siknet]

模板风格开发方便吗？

[yushiro]

@star7th 我就是用了代理才发现可以访问，前几个月想用来着，结果发现 UI 全是乱的，我以为公司跑路了呢

[star7th]

@siknet 挺不方便的，因为 showdoc 看起来简单，但其实有很多很多细节。很多细节没有从一开始做成变量或者方便批量切换，所以要做在运行时换一套模板或者皮肤都不容易。而且我觉得嘛，模板不是刚需，可以暂时不用花精力。

[star7th]

@yushiro
我找了挺多香港 ip 来做测试，ip 库都显示正确。像你的那种情况，应该是因为 ip 被识别为大陆内地了——但实际网络是香港，所以才有这个问题。我估计应该是特例，因为我测试其他香港 ipi 都是正常的。
如果方便的话你可以把 ip 段告诉我下。或者你就针对 showdoc 使用代理访问吧。

[815979670]

问一下 showdoc 商业版的数据库也是 sqlite 吗？还是换了 MySQL 之类的？

[star7th]

@815979670

官网的并发，sqlite 肯定扛不住的。用了 mysql 和 redis 。

[star7th]

@815979670 实际上官网版跟开源版，很多数据库结构都不一样了。官网版我都是单独维护的。

[dcsite]

说实说，这个 UI 一如既往的难看…… 要是出个 GITBOOK 的主题就好了。

[star7th]

@dcsite
说实话，gitbook 当然不难看，但是如果将它封为效仿的标准，感觉就不是很有必要，因为是两种风格不一样的产品。
我推出 3.0 版后，除了你，没有一个人说难看的。最多就是说细节没到位，还可以完善，但远谈不上难看。

[u21t20o15]

希望可以做到自动化生成接口文档到私有部署的 showdoc ，然后 RunApi 能同步私有部署的 showdoc 接口数据进行本地化调试，提升开发效率。
目前在用 Apidoc 插件（注解生成接口文档）和 Yapi ，但是 yapi 不能保存调试的参数，每次都要重新写请求参数

[star7th]

@u21t20o15

RunApi 已经可以做到自动化生成接口文档到私有部署的 showdoc https://www.showdoc.com.cn/runapi

runapi 无法同步历史 showdoc 项目到客户端，因为历史上使用 markdown 编写，不是结构化数据，转不回来。但是从 runapi 创建的项目都可以自动生成文档到 showdoc

[star7th]

@u21t20o15

如果你要用注解生成 api 的话，可以参考这里
https://www.showdoc.com.cn/page/741656402509783

我推荐的做法是，注解生成 runapi 项目。而 runapi 项目会自动生产 showdoc 项目。从而实现你说的需求，即：
可以注释生成文档，并且生成的接口在 runapi 可以调试

[CaffreySun]

我也在用 ShowDoc ，我觉得问题不是出在 UI 难看上，而是排版和配色上，说白了就是没有 gitbook 可读性强，
gitbook 将大片显示区域留给内容，内容两侧有大片空白，目录位于最右侧，在看内容时视觉上没有干扰。
gitbook 整体字体更大更利于阅读。
gitbook 排版细节更好，
比如标题上边距大于下边距，从空间上就能知道这个标题是下面内容的标题
再比如段落之间的间距要大于段落内行间距，从空间上很容易区分段落。
还有就是配色问题，ShowDoc 整体配色颜色很多，显的有点凌乱

[geekboy]

希望可以加上评论功能

[star7th]

@CaffreySun

showdoc 没办法像 gitbook 那种将大片显示区域留给内容，因为两者面向的文档类型不一样。

像 gitbook 这样的大片区域，非常适合文字段落饱满的情况，比如写一篇教程，文字或者代码非常饱满，可以充满一个个段落的。
但是 showdoc 没办法，因为 showdoc 大部分用来解决 api 文档场景。写 api 文档，段落是不饱满的，我自己测试过，在锻炼不饱满的情况下，不同分辨率下的视觉效果无法统一，且都不算好看。
至于说排版细节，那就确实是的，showdoc 有不少要改进的地方。但无论如何，都不能直接仿照 gitbook ，因为主要面向的文档类型不一样。

至于说配色的问题，我后面会咨询设计师意见，后面再做个更完善的版本。

[star7th]

@geekboy

评论需求是一个很模糊的需求。说需要嘛，这几年来用户的呼声不大。说不需要嘛，偶尔会有人说。https://github.com/star7th/showdoc/issues/553

我自己依然没想好。再确认之前，我可能暂时先不动手做这个，因为评论功能会强势地占用视觉空间，并不是躲在一个二级菜单里等着用户使用就好。

[sairoa]

代码块输入英文单引号会被转义，保存后页面显示为`'`。

[star7th]

@sairoa 昨天晚点的时候发布了 3.0.1 版，就是修复此问题的。你更新下。

[gongquanlin]

用了好几年了，一直在用。牛逼，加油。什么时候能优化一下移动端就牛逼了，现在在手机上用 app 会有很多错位 /占满的问题

[star7th]

@gongquanlin

移动端好久没更新了，因为用户少，大部分用户都是电脑上把 showdoc 当生产力工具使用。有空再看看移动端吧

[idragonet]

3.0 怎么编辑框，有时候 ctrl+c 容易导致编辑框消失？

[star7th]

@idragonet

去官网试一下 有没有这样的问题 https://www.showdoc.com.cn/ 如果官网没问题，那可能是开源版滞后。你需要更新一下。