# PR #2394 完整报告

- 仓库：`radixark/miles`
- 标题：docs: let tables wrap instead of silently clipping at max-content
- 合并时间：2026-08-13 04:25
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2394

---

## 执行摘要

本 PR 通过重置 `docs/style.css` 中表格的 `max-content` 与 `nowrap` 规则，并新增 `th, td { min-width: 0 }` 覆盖 Mintlify 的 150px 单元格下限，修复了全站 34/178 张宽表格在文档页右侧被静默裁剪的问题，让表格按内容自适应换行。变更仅 1 个文件、24 行，纯静态样式层面，无运行时行为影响。

## 功能与动机

PR body 指出，自定义样式强制 `table { width: max-content }` 和 `th { white-space: nowrap }` 后，宽表格渲染为“content silently cut off at the right edge”，且没有任何提示表明右侧还有更多列。原规则本意是让宽表格可滚动，但 Mintlify 已为每个表格自带横向滚动容器，表格自身的 `overflow-x: auto` 永远不会触发，规则只保留了“不换行”这一有害副作用。作者用 headless Chrome 全站审计（1280/1440 视口）确认 34 张表被裁剪，其中模型配方页的 8-9 列并行配置表隐藏了整列参数，`advanced/p2p-weight-transfer` 的组件表被裁掉 2105px 说明文字。

## 实现拆解

1. 移除 `docs/style.css` 中 `table` 的五条规则：`display: block`、`overflow-x: auto`、`-webkit-overflow-scrolling: touch`、`width: max-content`、`max-width: 100%`，让表格恢复浏览器默认的 shrink-to-fit 布局，列宽随内容与列宽自动折行。
2. 移除 `th` 的 `white-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 扫描 70 个导航页 178 张表，除一张 min-content 超宽的 p2p benchmark 表（1440px 下残余 13px 可滚动）外全部无裁剪；并用 CSSOM 禁用旧样式后注入新文件模拟线上环境，与 `mint dev` 渲染结果核对一致，另覆盖 390px 移动端视口。验证为脚本 + 截图的人工审计，未沉淀为仓库内自动化测试。

### `docs/style.css`

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

```css
/* 表格不再强制 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;
}

```

## 评论区精华

本 PR 没有任何 review 评论线程，维护者 Shi-Dong 直接 APPROVED。值得记录的“讨论”实际来自 PR body 作者自述：对 p2p benchmark 表残余 13px 溢出、代码 chip 换行不美观、以及未来建议精简该表列（`sglang Model Class` 列与上方表格重复）的坦诚披露，体现对残余风险不回避的态度。

## 风险与影响

- **全局样式风险**：`th, td { min-width: 0 }` 影响所有表格，未来新增含长 URL 或不可断行代码的表格可能出现与前不同的换行 / 溢出行为，需靠视觉检查发现。
- **残余滚动盲区**：min-content 超宽的少数表格仍回退到 Mintlify 隐藏滚动条，用户依然可能察觉不到右侧列存在，只是裁剪范围从“整列不可见”缩小为“少量溢出”。
- **层叠机制依赖**：覆盖依赖 unlayered 样式优先于 layered utility 的 CSS 行为，Mintlify 升级后可能失效。
- **影响面**：全部 70 个导航页 178 张表格的渲染方式改变，34 张此前被裁剪的表恢复完整可见，阅读收益明显；纯静态样式变更，无构建、运行时或接口影响。

## 关联脉络

历史 PR 中与本 PR 最相关的是 docs 站点质量改进线：PR 2411 删除首页过期更新日志、PR 2400 补齐 SEO 元数据、PR 2395 清理重复的平台文档，均属文档站内容与结构打磨。本 PR 首次针对 `docs/style.css` 的表格渲染做修复，是这条维护线向“展示层”延伸的一步；未来可考虑把 headless Chrome 表格裁剪扫描沉淀为 CI 视觉回归测试，并从精简 p2p benchmark 表列数入手消除最后的隐藏滚动盲区。