可能是国内颜值最高的开源文档工具？

[star7th]

地址

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

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

开发小故事

早前，showdoc 发布过 3.0 UI 重构版，但是尚未完全达到设计预期，属于略微仓促发布的版本。在那个时候，设计师委婉地说过，他习惯一步到位，做完善产品了再上线。意思是想我更完善 showdoc 再发布。

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

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

于是在 3.0 版发布了一段时间后的今天，3.2 完全版也出来了。本轮更新，在设计师的“像素眼”注视下，修改了大量细节，优化了很多视觉 UI 和交互体验。

3.2 版本更新了什么

• 文档目录数支持拖曳排序和右键菜单操作，可以快速添加页面以及子文件等
• 优化移动端访问项目的效果
• 更换了更好看的产品图标
• 优化小屏设备的访问效果
• 将大多有跟 页面 有关的操作移动到文档目录树底部操作栏
• 其它小细节

相关截图

给新用户看的 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

感觉这个标题似乎 招来了一些不友好的言论 。

如果硬要从客观上看，本标题并没有脱离事实太多，因为国内开源文档工具很少，我在一个小众产品领域里说可能 [颜值] 最高，虽然不是非常离谱的乱说，但是也不算厚道谦虚，所以可能激起了某些人的反感情绪。

所以我承认这个标题起得不算好了。下次不这样起标题了。

后面的人就暂且不要从标题上讨论了，重点关注讨论下产品本身吧。

V 站不能改标题，所以这个标题我暂时没法修正了。也不知道后来者能不能看到文后的附言，不用再标题上深究下去了。不然我每个人解释一下，也很累的( ╯□╰ )

其实，showdoc 开源项目都维护 7 年了，我如果真的很浮躁地运营产品，只靠哗然宠，是坚持不了那么多年的。大部分时候都是默默踏实完善产品。此次是宣发的时候，失误地想标题党一下，想吸引下流量。正文还是比较中规中矩的宣发。
各位就不要死抓我这次标题的失误，谢谢啦。

[SillyGod]

@akring 你 Safari 的 tim 是个插件？干啥的啊

[luohechen]

粗略扫了一眼，发现大多评论都是说 UI 的，没什么人说使用 😂

[star7th]

@dandycheung

以前 showdoc 确实是不算好看。但是现在，我还是有点自认比 mindoc 好点的。毕竟他没怎么更新了。

[star7th]

@96

感谢建议。我后面参考下

[daimazha]

@luohechen #102 因为 op 的标题啊，大家都是被这个吸引过来的

[star7th]

@luohechen

这个就略伤心的，大部分都是吐槽的。

不过看 github 项目的情况，star 确实有增加了一些，还是有新用户因此使用的

[star7th]

@akring

这个图标是 svg 的，理论是矢量图不失真的。我晚点再留意下。

[uSy62nMkdH]

支持开源，审美见仁见智 OP 不用理会

[jixule]

@star7th 又用 edge 和 chrome 试了，无痕模式也试了，缩小不回来，报错信息看一下吧 TypeError: Cannot read properties of null (reading 'style')
at o.adaptToMobile (app.33807af49f79999d2f5a.js:1:305269)
at o.clickFullPage

[kujio]

很多人喷我感觉可能是应激反应。我个人感觉还行，很多地方讨巧了（比如小字体），问题确实有，但就我发现的都无伤大雅。要说带着情绪挑毛病，就没有完美的东西了。

其实只要是开源的，哪怕写的再烂，吹得再过，都应该是要包容和鼓励的。

[victorc]

在 27 寸屏幕上，显示非常狭小，一点也不大气，样式风格看起来很石墨早期很接近

VuePress 比你这个舒服多了

[yiikZero]

看了一下， 提两个小建议：

1. 你们官网首页的页脚使用的公司团队，那些 LOGO 都还是白底呢，有些粗糙。

京东： https://www.showdoc.com.cn/static/imgs/case-logo/jingdong.png
顺丰： https://www.showdoc.com.cn/static/imgs/case-logo/shunfeng.png

2. 我觉得首页每个功能模块，左边一张图，右边一些描述，这样子布局倒是没啥问题，但是。。信息量太少，文字层级也没分好，图片不够精致，就会显的很粗糙。 做一些动态效果、视差等都会精致些。

这个可以参考千牛，虽然信息量少，但是相对精致一些： https:work.taobao.com/

最后，作为一位设计，我想说 UI 设计的还是很粗糙的。。

[yiikZero]

@yiikZero 千牛链接出了点问题，重新贴一个： https://work.taobao.com/

[star7th]

@jixule

我知道全屏按钮的问题在哪了。晚点修复下。目前的 bug 只是对 无权限的游客产生，登陆了的管理员或者成员是 ok 的，难怪我一开始无法重现。

[star7th]

@victorc

目前是比较照顾主流屏幕。你这个 27 寸是有点大，晚点看看对大屏能做些什么优化

[star7th]

@kujio

感谢肯定。

[star7th]

@yiikZero

感谢你建议，我后面优化下。

[manasheep]

apifox 就很好用

[iloveoovx]

我只説下爲什麽大家對這種宣傳方式本能反感的原因：
這裏多是程序員，接觸的程序從一開始就不分國籍。雖然從你的角度，想要找一些宣傳點，但是這個點對於這裏的用戶來説沒有實際上的影響，只有心裏層面的影響，也就是一層額外的認知負擔。至於目前的情緒下的民族主義氛圍也不用多提了，總之對於用工具的各位來説，能不被那些東西裹挾就不希望被裹挾，因爲也沒有實際作用。所以你用這個點來作爲限定條件説事，是讓大家更麻煩的事情，雖然沒有什麽 618 XX 價位銷量排名第一這麽極端，但本質上都一樣，別人不關心，也只是自 high ，這裏還加了個道德高地，大家早就煩不勝煩了。

[star7th]

@manasheep

showdoc 不是对标 apifox 的，showdoc 更多只是文档功能，不包含接口测试这些功能。你可以看一下我另一个产品 runapi https://www.showdoc.com.cn/runapi 它就是对标 apifox 的，我感觉并没有比 apifox 差多少。

[zilan]

IP 新加坡，403

[encro]

自信了啊，
vue press 可能比你高那么一丢丢。。。
虽然不一样，
但是可以学习下嘛
老早想给你提一提意见了。

[keepsjh]

官网好歹用个 2x 图，糊成什么样了都。

[star7th]

@zilan

看你这个图应该是 ip 被 cdn 节点拒绝连接了，所以静态 js 加载不到。晚点看看原因。当前，你尝试用个其他的代理 ip 看看，比如说美国翻墙代理

[Varobjs]

说实话没看出来哪里有「设计」

[star7th]

@jixule @deplivesb

已在官网修复全屏按钮失效的问题。开源版晚点同步更新。

[luhongfei66]

哈哈 OP 已经知道标题错了就算啦 开源还是支持 加油搞

[imNull]

docker 部署，忘记了密码，按照文档提示执行后，报错 `Undefined constant "Think\_PHP_FILE_"`

[Varobjs]

接口文档这种东西
要不用 swagger 这种生成的
要不用 slate 这种好看的

[ainon]

用过开源版本的，漏洞比较多，功能上还是太简单了

[star7th]

@ainon

也不算 漏洞很多吧。 就两年前有个图片上传的漏洞被黑客逮住了。其他的基本都是小毛病。现在白帽子已经帮我找的差不多了，暂时还没发现有大的漏洞。
至于功能，你大概是想说接口调试之类的功能吧，这块，showdoc 的解决方案是单独出个 runapi 客户端，你可以看一下 https://www.showdoc.com.cn/runapi

[smilzman]

我是一直在用的，从之前不怎么好看的界面到现在还可以的界面，其实就技术文档来讲，简单、简洁就好了，当然之前有部署过的类似 https://3x.ant.design/docs/react/introduce-cn 这种效果的，我觉得比较好看，忘记名字了，效果基本上差不多。

[luoshuhui]

好好的程序员，非要去学罗永浩，被骂活该

[zilan]

@star7th #124 我人在新加坡，没有什么代理 😂

[littleBink]

@star7th #115 公司主流显示器尺寸就是 27 吧

[star7th]

@grahamsa0503

那我对寸数一时间没反应过来。我现在想得更多是分辨率。内容居中是想保持 内容在不同分辨率下的一致性阅读体验。不然的话，若 全屏展示内容，不同屏幕下就没法一致了，效果可能会差

[chinaq]

哈哈，评论的大家才是真像素眼，现在互联网到底什么帖子才能做到没有戾气。可能有些人水平就在那，只能提提无关痛痒的问题显示自己的存在。有意思的是，一方面大家不喜欢这样的标题，但是又通过评论让它热度不断提高被更多人看到。这可以说是一个双赢的局面，OP 获得了流量，大家发泄了情绪。

[star7th]

@chinaq

从客观上来讲，其实标题党确实获得了更多关注。
但是我脸皮薄，下次不这么标题党了，还是想好好做口碑。

[xcatliu]

Pagic 请求一战 https://github.com/xcatliu/pagic

[pan020037]

showdoc 挺好的，一直有用

[iyobucuo]

好东西，已收藏

支持 op

[star7th]

@iyobucuo

感谢肯定。

[star7th]

@xcatliu

我个人感觉 showdoc 不输 pagic 哈。但是我也不说坏话，感觉还是在同一个层次的产品，也没有明显差距。可以交由用户去评价。

[zetttt]

设计细节很弱，如果按「像素眼」的要求，针对 demo 页，我提几点个人感受

1.阴影很虚，全部使用 0 0 Xpx 的阴影，会让整体看起来很不自然

2.间距很诡异，看到很多 10px 、25px 、16px 、.5rem 的值，使用的很随意，没有规则，导致多处看起来有的间距过窄、有得过大，建议使用按一定规则计算后的间距值，同样的问题在圆角处也存在

3.正文标题栏，存在外边距塌陷问题，导致上边距高 10px ，看起来没有垂直居中，很膈应；页面视图全屏切换时，字体大小、间距抖动很厉害，切换后正文 table 表格会变得偏左对齐，应该是个 bug

4.正文字体 13px 在大屏幕小有点过小了，各级标题对比、行间距这些看起来也有点过密集，建议多一些间距和留白

5.色彩上，如果页面不是纯黑白灰，背景不建议使用纯灰色(R G B 值相同)，混一点其他颜色会更高级；正文中文字颜色好像只有#333 一种，建议标题更黑一点、正文稍浅一点，阅读效果会更好； table 表头建议改为更深的颜色或使用更浅的背景色+深色文字，现在的浅色背景+灰色边框视觉上感觉像是表头窄了 2 像素


举点个人觉得设计不错的例子

中文文档，石墨文档 https://shimo.im/
设计细节，即时设计官网做的不错 https://js.design/

[star7th]

@zetttt

感谢反馈，我参考下。

[99s]

给个建议：官网没有体现产品的功能，浏览下来都是些假大空的话，首屏放个产品演示视频更加一目了然，还有就是不要吹牛逼！

[fregie]

不管是不是国内最好看的
反正确实不怎么好看

[shunia]

@zetttt #144 js.design 页脚的 logo 居然是一个 1800 的图，然后看起来缩放后都变格子了。。。
石墨真的很丑，虽然 js.design 到处都是圆角未必多好，但是到处都是大方块子也真的让人喜欢不起来。

[zetttt]

@shunia 每个人喜好不一样，我只是讲石墨文档的中文文档部分和即时设计的设计细节，个人觉得不错

[timnottom]

你都说了"颜值最高"，大家就肯定是以最高的要求来看，，结果就是不符合要求

[lxyer1]

@divilbs #63 赞同，厚重的历史感

[DosLee]

我读到这个标题，突然感觉这个标题给我一种，我在评论区经常看到的：“200 元以下没有好耳机”，然后这条评论的回复都是推荐 200 元左右每个人认为的好耳机。

颜值上来说，这个配色很压抑。每个人理解不同吧。

[ye4241]

想知道为何 H1 H2 不能 hash link 直接跳转的？这样子分享文档特定位置的 url 不会很麻烦么？

[Cyshall]

没有暗黑模式吗？

[tduck]

支持支持！
确实相对来说是 zui 好看的文档了。
风格非常喜欢，极简！

标题确实比较吸睛，有争议那这个标题就成功了。

借楼宣传下：可能是国内开源社区颜值最高的问卷调查工具？
https://gitee.com/TDuckApp/tduck-platform

[zhangxudong]

一直在用

[star7th]

@ye4241

官网的可以的.
开源版的不支持，因为开源版的 vue 路由本身使用 hash 模式

[star7th]

@Cyshall

目前是没有的。以后考虑下

[ye4241]

@star7th #157 原来如此

[l1ve]

恕我直言... 真的算不上有多好看
我自己产品在用的文档程序
https://wiki.frappe.cloud/wiki/new-wiki-page
https://docs.erpnext.com/docs/v13/user/manual/en/introduction

之前在找文档的时候有看到过楼主的，当时感觉有点难看，现在感觉.... 好了一些但不多
首先配色方面感觉有点上古互联网风和现代风糅合到一起的感觉
想了想终于想到一个合适的比方
就是 windows 的 chm 帮助文档既视感
https://imgur.com/TeMAudL
然后最可气的是文档的图标
这个默认图标和这个配色，简直丑爆！！！
https://imgur.com/pcFhIvo

最后祝楼主加油... 做的再好看点

[wushigejiajia01]

2015 年~2017 年之间，好像是用过这个的，当时一个小开发团队，用的还是挺舒服的

[Anivial]

OP 发帖的初衷应该就是引流，这个标题也确实很吸引人，所以当人点进来查看后发现和心理预期差距很大，表达反对的观点是一件很正常的事情，当然很多人会偏激的评价，这也是这种标题必然会带来的结果。
另外，看了内容后会感觉示例空洞，UI 不统一不像专门是设计师设计的（左侧边栏的突出显示偏淡，表格的表头颜色又太突出，代码块中的代码样式又没有颜色），这里推荐 https://dribbble.com/ ，你可以看看真正受大多数人欢迎的 UI ，风格是很统一的。
当初选型团队内使用的 API 设计沟通工具的时候就看见过 OP 的产品，私有化部署确实很吸引人，但是对比 apipost ，apifox ，yapi ，你会发现你的优点很少甚至很容易替代，API 文档一般都会由后端编写，你要知道 swagger 呢么一般的页面都有呢么多人用，那么也应该明白 UI 不是吸引人来使用的亮点，亮点应该是便捷性。
比如你可以了解下最近出的 AI 自动生成 API 文档

[ciki]

很早就用过，感觉一般吧

[star7th]

@Anivial

showdoc 不是对标 apipost ，apifox ，yapi 这些的，showdoc 更多只是文档功能，不包含接口测试这些功能。你可以看一下我另一个产品 runapi https://www.showdoc.com.cn/runapi 它就是对标 它们的，我感觉并没有比 它们差多少。

[star7th]

@wushigejiajia01

哇，好久前的版本。那时候的版本其实比现在丑好多( ╯□╰ )

[star7th]

@Anivial

感觉建议，我研究下

[star7th]

@l1ve

表格头的颜色，我刚改了下，改成比较淡的蓝色了。

[liuw666]

不够好看，感觉差点意思，页面风格也没有做到统一

[ttwxdly]

细节需要打磨。边距有点阴间。继续加油吧！

[Anivial]

@star7th 如果是文档的功能，那么 UI 的美观应该就是第一位了，我随便搜索了下，你可以看看，https://dribbble.com/shots/20928638-In-app-Onboarding 单纯这一个页面就已经让人很舒服了吧，这样的 UI 才是能被大多数人认可的

[rekulas]

能不能加个手动关闭更新提示功能

[jokeface]

个人感觉 sphinx 更有 geek 内味儿

[rekulas]

另外 runapi 客户端颜色搭配还有点乱，虽然走的简约路线但是很多版块感觉糅杂在一起不容易区分，建议优化

[star7th]

@rekulas runapi 后面看看怎么优化吧

[dandycheung]

@star7th 我抽空看看有哪些进步。坚持一件事挺不容易的，其他人有点不同意见也不用在意。

[lucybenz]

UI 可能只是参考些样式 可能并没有做专业设计 可能看起来业余玩家中算上等 官网披露的一些数据可能有些水分？

[xixibb]

@star7th #55 不好看就是不好看，和发泄情绪有什么关系呢？说你的好看就不是发泄情绪了？你是给用户用的，现在用户说不好那就是不好看。

[zmqking]

温馨提示：此贴标题涉嫌触犯广告法……

[Naccl]

没有挑刺的意思，团队内也是人人在吐槽，说个感受，细节不够，如果能有其它选择，我是肯定不愿意用的。
举几个例子，可能是之前的版本，runapi 里字段类型选择 int 、list 之类的保存后，再次编辑保存后，全部重置到 string 了。对 mac 兼容不好，有段时间启动 runapi 要花一分钟。command+Q 无法关闭 runapi 。目录树里新建的文件夹，很难把请求拖进去。
具体是什么版本没注意，有没有修复也不太清楚，不愿意在文档工具上花太多精力研究。
以至于大家宁愿用 apifox 之类调完接口后，生成 markdown 贴进 showdoc 里。
showdoc 页面也是很简单，给我总体的感觉就是半成品。如果作者是个人维护精力有限，建议还是多把宣传的精力放在仔细打磨上，好好设计下，希望不会挫了作者的维护积极性🥲。

[yushiro]

用过 showdoc ，对于小公司，小团队，的确挺合适的

[star7th]

@xixibb

在这里，大部分带有一点情绪来吐槽的，往往都不是 showdoc 用户。我是抱着接受建议的想法来看看对方有什么想法。但是如果对方不好好说话，我就没必要听。包括你。你永远都不会是 showdoc 用户，别在这里以用户的身份压我。

我还是那番话，谁好好讲，有理有据，我虚心接受谁。谁闹情绪的话，我也没必要惯着他。

[star7th]

@Naccl

重置字段那块是有历史包袱，目前只是 Query 会重置，其他不会重置。严格来讲，Query 页都是 url 参数，都应该是 string 类型，只有 strging 才能组成 url 。但是在这里，太严格了并不人性化。我后面看看能否处理吧。

重启要花一分钟的情况，暂时我没听过其他用户反馈。建议你下载新版试试。

新建文件夹，要把请求拖进去，方式是，用鼠标拖着接口到目录的上方，然后右移动，示意让接口成为目录的子节点。

[dingyaguang117]

颜值高的产品挺多的：
https://elements-demo.stoplight.io/?utm_source=github&utm_medium=elements&utm_campaign=readme#/operations/post-todos

[star7th]

@dingyaguang117

感觉它的布局并不优秀，比如说， 左上方的 star 数字框的右边距没有跟目录数对齐 。Try it 按钮，两边的边距不居中，太靠近搜索框了。

但是，这个产品的配色看起来很舒服，值得参考

[kylix]

耐心从头看到尾，结果 OP 还是那个态度。。。比较失望吧

[star7th]

@kylix

我也挺失望的。理性的人不多。

[star7th]

@kylix

你如果真的耐心看完，就会发现，对方的态度，就是我的态度。
上面，但凡好好说话的人，你看哪一个我不是虚心接受的？即使有不同意见，我也是平心地说出我的理据。
但凡不好好说话的人，我没啥太好的态度。
将心比心。

[wsseo]

首先，登录页面颜值就很低

[dode]

demo 页面点击导航栏会抖动

[Jack9527]

docsify 这个文档工具的 UI 很好看, https://docsify.js.org

[qiujianzhong]

用过，支持楼主一下，👍🏻

[xuanli]

用了挺久了，支持

[WhatWhatWhat]

一直在用，用起来很方便，点赞

[star7th]

@Jack9527

我参考下

[star7th]

@qiujianzhong

@xuanli

@WhatWhatWhat

感谢支持

[star7th]

@dode

抖动是已知的问题，主要是渲染右侧标题目录树的时候渲染引起的。当时一时间没找到思路，姑且算罢。等有空回头看一下。

[jenhe]

评论就能看出国内开源起不来的原因

[sigl0p]

不觉得是最好看的，感觉 markdown 渲染出来的和这个也差不多。而且 API 文档，我看我公司搞 IT 的同事用的是 APIFOX 之类的，能够自带接口测试，现在用在线文档记录 API 我不知道还有多大意义，毕竟我也不是搞这方面的。

[star7th]

@sigl0p

showdoc 不是对标 apifox 之类的，showdoc 只是纯文档工具。如果你想调试接口什么的，有专门的客户端，这个才是对标 postman 之类的 https://www.showdoc.com.cn/runapi

[star7th]

@jenhe

是啊，太难了