Prhub

#2394 docs: let tables wrap instead of silently clipping at max-content

原始 PR 作者 nblintao 合并时间 2026-08-13 04:25 文件变更 1 提交数 1 评论 0 代码增减 +18 / -6

执行摘要

修复 docs 表格被 max-content 裁剪,改为自动换行

PR body 明确指出:强制 max-contentnowrap 表头会让宽表格渲染成“content silently cut off at the right edge”,且没有任何提示表明右侧还有更多列;全站审计发现 34/178 张表被裁剪,最严重者隐藏了整个结果列或 2105px 的说明文字。原规则本想实现可滚动,但 Mintlify 已为每个表格包裹了横向滚动容器,导致表格自身的 overflow-x: auto 永远不触发,规则只保留了破坏换行的有害副作用。

值得快速浏览而非精读:变更本身只有 24 行 CSS,但 PR body 的“问题根因 - 全站审计 - 修复 - 残余风险披露”结构是高质量文档修复的范例,其中 unlayered 选择器覆盖 Mintlify layered utility 的技巧和 headless Chrome 批量截图验证方法可复用到其他样式类问题。建议关注作者对残余风险(隐藏滚动条)的诚实说明,以及未来对 p2p benchmark 表做列精简的 follow-up。

讨论亮点

本 PR 没有任何 review 评论线程,维护者 Shi-Dong 直接 APPROVED。讨论信息主要来自 PR body 中对裁剪根因、验证方法和残余风险的完整自述(例如 p2p benchmark 表在 1440px 下仍有 13px 宽度依赖隐藏滚动条、类名代码 chip 换行不美观等),这些均属作者主动披露而非评审交锋。

实现拆解

  1. 移除 docs/style.csstabledisplay: blockoverflow-x: auto-webkit-overflow-scrolling: touchwidth: max-contentmax-width: 100% 五条规则,让表格恢复浏览器的正常 shrink-to-fit 布局,列按可用宽度自动换行。
  2. 移除 thwhite-space: nowrap,表头文字不再强制单行,长表头可以折行展示。
  3. 新增 th, td { min-width: 0 },清零 Mintlify 通过 Tailwind utility 施加的 [&_td]:min-w-[150px] 下限;该下限单独就足以把 9 列表格撑到至少 1350px 宽,而内容列仅约 719px。此处利用“不带 layer 的元素内样式优先于 layered utility”的层叠机制(与同文件 img 规则相同)实现覆盖。
  4. 验证配套:使用 headless Chrome 在 1280/1440 视口扫描全部 70 个导航页的 178 张表格,结果为 0 张裁剪(除 p2p benchmark 表残余 13px 溢出可滚动);同时用 CSSOM 禁用旧样式表并注入新文件模拟线上环境,与 mint dev 渲染结果核对一致,并覆盖 390px 移动端视口。该验证是作者手工脚本 + 截图对比,未沉淀为仓库内的自动化测试。
文件 模块 状态 重要度
docs/style.css 文档样式 modified 3.85

关键源码片段

docs/style.css core-logic

全站表格渲染规则的唯一改动点:移除强制 max-content/nowrap,新增 min-width:0 覆盖 Mintlify 的 150px 单元格下限,直接决定 178 张表格的展示方式。

/* 表格不再强制 max-content:
   移除 display:block / overflow-x / width:max-content 和 th 的 nowrap 后,
   浏览器恢复正常的 shrink-to-fit,列会按可用宽度自动换行。
   Mintlify 已为每个表格包一层横向滚动容器,因此表格自身无需 overflow-x;
   旧规则只会把溢出内容塞进滚动条被隐藏的容器中,表现为右侧静默裁剪。 */
table {
  border-collapse: collapse;
  font-size: 0.9375rem;
}/* 表头不再强制单行,长表头可折行 */
th {
  background: var(--rx-table-bg);
  font-weight: 600;
  letter-spacing: 0.01em;
}/* 清零 Mintlify 的 150px 单元格下限([&_td]:min-w-[150px]):
   仅该下限就会让 9 列表格至少 1350px 宽,而内容列约 719px。
   此选择器不带 layer,优先级高于 Mintlify 的 layered Tailwind utility,
   与同文件 img 规则使用的覆盖机制一致。 */
th,
td {
  min-width: 0;
}

评论区精华

没有提炼出高价值讨论线程

当前评论区没有形成足够清晰的争议点或结论,后续有更多讨论时会体现在这里。

风险与影响

  • 全局样式影响:th, td { min-width: 0 } 对文档站所有表格生效,未来新增表格若含长 URL 或不可断行代码,可能出现与当前不同的换行或溢出行为,需依赖视觉检查发现。
  • 残余滚动盲区:极少数 min-content 超出内容列的表格(如 advanced/p2p-weight-transfer 的 9 列 benchmark 表)仍回退到 Mintlify 自带的横向滚动,而该滚动条被 scrollbar-width: none 隐藏且无边缘渐变提示,用户依然可能察觉不到右侧列存在,只是裁剪范围从“整列不可见”缩小为“残余少量溢出”。
  • 层叠机制依赖:本次覆盖依赖“unlayered 样式优先于 layered utility”的 CSS 层叠行为,若未来 Mintlify 升级样式层级结构,该覆盖可能失效。
  • 验证局限:仅覆盖 1280/1440/390 三个视口与默认字号,字体缩放、其他视口或暗色主题下的表现未审计,且没有自动化回归测试兜底。

影响范围为全部 70 个导航页面共 178 张表格的渲染方式:34 张此前被静默裁剪的表格现在能完整展示内容,其中模型配方页的 8-9 列并行配置表(Qwen3、GLM、DeepSeek、Kimi 等)和 p2p 组件说明表收益最大;对可正常展示的表格,布局可能从等宽紧缩变为按内容折行,部分表格高度增加。纯静态 CSS 变更,无构建、运行时或接口影响,团队合并成本低,但后续文档表格的审美验收需要留意换行效果。

全局样式变更 无自动化回归测试 隐藏滚动条残余溢出 依赖 CSS 层叠机制

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接,后续同步到相关引用后会出现在这里。

完整报告

参与讨论