最近给文档站补了些什么
这两天更新了文档站的依赖，也把首页入口、内容渲染和发布检查重新过了一遍。改动比较散，单看提交记录不太好找，放在这里记一下。
其中一个问题很直观：从首页点“文档”，再选巡检工具，明明内容文件在，却进不去。这个入口已经修好。后面又补了一批 MDC 组件，文档和博客都能直接用，下面顺带放几个例子。
先把点不开的文档修好
问题出在路径解析。浏览器中的 URL 和内容库记录的路径没有统一处理，中文编码、大小写和末尾斜杠混在一起，查询时就可能找不到对应页面。
现在先规范路径，再查询内容。巡检工具的首页入口、文档内部跳转、直接刷新和原始 Markdown 页面一起检查过，避免只修好其中一个入口。
顺手也核对了草稿的发布行为。生产构建会排除标记为 draft: true 的内容，导航、搜索和 Feed 等公开入口跟着使用公开内容。写到一半的稿子，就先留在草稿里。
依赖更新了，但没有硬追版本号
这次把 Nuxt、Content、UI 和测试工具等依赖更新了一轮。当前主框架是 Nuxt 4.5.2、Nuxt Content 3.16.1、Nuxt UI 4.11.3，包管理器使用 pnpm 12.8.1。
TypeScript 暂时留在 6.0.3。尝试升级到 7 时，ESLint 和 Vue 类型检查遇到了兼容问题，先退回能通过检查的版本。这件事留了工单，等工具链跟上再处理。
生产检查也补了些过去容易漏掉的地方：代码检查、内容链接、类型、单元测试、构建后的页面测试，以及 Go 微信签名服务的检查。Docker 增加健康检查，CI 里还会实际启动容器，确认内容查询和图片处理能跑。
这里记的是仓库里的改动，线上效果还要等发布后确认。
页面看起来正常，也可能藏着渲染问题
这次还修了图片、示例标题和公式样式的几个小问题。有些 HTML 结构浏览器会自行纠正，肉眼看不出来，但 Vue 接管页面时就可能发现前后结构对不上。
这里的 Hydration浏览器中的 Vue 接管服务端生成的 HTML，为页面连接事件和响应式状态。，就是服务端页面交到浏览器后的那一步。
图片容器和标题示例的结构调整后，服务端与浏览器保持一致；MathJax 生成的样式也单独处理了。代码主题、行号和图注设置则接上了实际渲染，刷新后会恢复已保存的选项。
另外，Studio 的生产入口现在默认关闭。需要在线编辑时再按部署说明启用，把 OAuth 和会话密钥放在运行环境里。
新组件，先从能用上的几个说起
以前写设备清单、参数说明，基本都靠普通表格。内容少的时候够用，行数一多，找东西就得来回翻。现在有了 DataTable，表格里能搜索、排序和分页。
下面把这次改动列成一张表。试着搜“组件”，或者点“类别”排序；清空搜索后可以翻页。
| 文档入口 | 统一路径解析 | 首页巡检文档入口、刷新和原始 Markdown 查询使用相同规则 |
| 内容发布 | 排除生产草稿 | 草稿不进入公开内容集合 |
| 页面渲染 | 调整图片、标题和公式样式 | 修复相关服务端与客户端渲染不一致的问题 |
| 阅读设置 | 联动代码主题、行号和图注 | 设置影响页面渲染，刷新后恢复选项 |
数据还是写在 Markdown 里，组件只负责页面内的查找和展示。没有给这个表另外接一个接口。
接口说明不用拆成几张表
ApiEndpoint 和 ParameterTable 可以放在一起。拿仓库已有的微信签名接口举个例子，方法、路径、参数和请求响应都放在一个块里：
获取微信 JS-SDK 签名
/api/wechat/js-sign响应状态：200
这是独立 Go 服务提供的接口，需部署服务并配置允许的来源和签名域名。这里只展示格式，响应中的值是占位示例，不能用于微信初始化。
| 参数 | 类型与默认值 | 说明 |
|---|---|---|
url必填body | string | 需要签名的页面完整地址；域名需在服务端白名单中，hash 会被移除 |
请求示例
POST /api/wechat/js-sign HTTP/1.1
Content-Type: application/json
{ "url": "https://lijue.net/docs" }
响应示例
{
"appId": "wx-example",
"timestamp": 1791043200,
"nonceStr": "example-nonce",
"signature": "example-signature"
}
这个组件不会请求上面的接口。它解决的是“说明怎么排”，真要测试接口，还是用自己的客户端或命令行。
长说明可以收起来，源码也能放进去
ExpandBox 是一个折叠块。参数不多时把代码放进去，正文就不用同时铺开效果和源码。点开下面这段，可以复制一个最小的接口说明：
查看 ApiEndpoint 的 MDC 写法
:::api-endpoint{title="查询示例报告" method="GET" path="/api/reports/{id}" :status="200"}
这是一个虚构接口，仅用于说明布局。
#request
```http
GET /api/reports/demo HTTP/1.1
```
#response
```json
{ "id": "demo", "status": "ready" }
```
:::
组件名用短横线写，嵌套时外层多一个冒号。上面的 #request 和 #response 是插槽名，不是文章标题。
示例文件有个明确的下载位置
文章里附配置片段，读者有时想直接拿文件改。DownloadCard 可以把文件名和用途放在链接旁边：
设备清单示例 JSON
两条文档示例地址，不含账号密码；字段需按实际工具格式调整。
这个文件用来演示下载，不是巡检工具的正式配置模板。文件放在 public/ 中，卡片指向它已有的地址。
操作指南可以加一份核对清单
清单能勾选，也能看到完成了几项。写部署说明、故障排查记录时，放在最后比较合适。
勾选只保留在当前页面，刷新就恢复初始状态。如果需要长期记录执行结果，那是另一项功能。
ContentQuiz 也采用相同的页面内交互方式，适合教程里的小题。比如检查一下刚才的插槽写法：
答案写在公开内容里，组件只给阅读反馈，不记录成绩。
说明也一起补上了
这轮还加了摘要、链接卡片、引用、数字概览、时间线、图库和图片对比。连同原来的卡片、标签页、文件树等，目前有 27 个公共自定义组件。普通段落能说明白的地方，仍然直接写 Markdown，不需要每一节都套卡片。
“简单文档”里补了一篇 在文章中使用组件，把效果和可复制的代码放在一起。查参数可以看 常用组件，想试图库、图片对比等交互，就去 内容组件演示 和 进阶组件演示。
后面写巡检工具说明、排障记录和配置指南时，就可以直接用这些现成的块了。