——
OpenClaw 文档优化实践：5个页面如何修复92个排版问题
技术文档的质量直接影响开发者体验。OpenClaw 作为开源 AI Agent 网关平台，近期通过一次精准的文档优化，将 5 个核心页面的 92 个排版字符标准化，并消除了重复的 H1 标题问题。本文将拆解这次更新的技术细节，为技术团队提供可复用的文档治理方案。
—
为什么排版卫生（Typography Hygiene）很重要
技术文档中的”小字符”往往藏着大问题。弯引号（" "）、撇号（'）、破折号（— –）等非 ASCII 字符，在不同终端、搜索引擎爬虫和自动化工具中可能呈现为乱码或不可预测的锚点链接。
OpenClaw 团队遵循 docs/CLAUDE.md 中定义的 heading 与 content hygiene 规则，将以下字符统一替换为 ASCII 等价形式：
| 非 ASCII 字符 | ASCII 替换 | 常见问题 |
|:—|:—|:—|
| ' (弯撇号) | ' (直撇号) | 代码复制时语法错误 |
| " " (弯引号) | " (直引号) | JSON/YAML 解析失败 |
| — – (破折号) | - (连字符) | URL 锚点断裂 |
| 非断连字符 | 标准连字符 | 搜索索引不一致 |
—
5 个页面的具体优化清单
1. 飞书/Lark 集成文档 (docs/channels/feishu.md)
改动规模：19 个字符替换 + 移除重复 H1
---
title: "Feishu / Lark"
---
Feishu / Lark ← 重复！Mintlify 已从 frontmatter 渲染标题
---
title: "Feishu / Lark"
---
正文直接开始...
关键问题：/ 斜杠在标题中会产生脆弱的锚点链接（如 #feishu--lark），影响文档内导航的稳定性。
—
2. Bonjour/mDNS 发现文档 (docs/gateway/bonjour.md)
改动规模：18 个字符替换 + 移除重复 H1
Bonjour 是 OpenClaw 网关层实现零配置网络发现的核心协议。该页面的 H1 重复问题与飞书文档类似：
Bonjour / mDNS discovery
—
3. Matrix 协议文档 (docs/channels/matrix.md)
改动规模：19 个字符替换
Matrix 作为去中心化通信协议，其文档中的代码示例对字符精确度要求极高。ASCII 标准化确保开发者复制配置时不会出现隐藏字符错误。
—
4. 浏览器工具文档 (docs/tools/browser.md)
改动规模：18 个字符替换
OpenClaw 的浏览器自动化工具支持通过自然语言控制 Web 页面。标准化后的文档确保命令示例在任何编辑器中均可直接执行：
优化后的命令示例（无隐藏字符）
openclaw browser navigate --url="https://example.com"
—
5. 定期任务自动化文档 (docs/automation/standing-orders.md)
改动规模：18 个字符替换
Standing orders 是 OpenClaw 实现定时 AI 工作流的关键功能。清晰的排版降低配置出错概率。
—
Mintlify 渲染机制与 H1 最佳实践
OpenClaw 使用 Mintlify 作为文档平台。理解其渲染逻辑是避免 H1 重复的关键：
渲染优先级：frontmatter title > 第一个 H1 > 文件名
问题场景：
- frontmatter 定义了 title: "Feishu / Lark"
- 正文又写了 # Feishu / Lark
- 结果：页面出现两个相同层级的标题，且锚点生成冲突
推荐模式：
---
title: "页面标题" ← 唯一标题来源
description: "SEO 描述"
---
快速开始 ← 正文从 H2 开始
内容...
—
如何在自己的项目中实施排版治理
步骤一：建立字符白名单
创建 docs/STYLE_GUIDE.md：
允许的字符集
- 引号：仅使用
" 和 '
- 破折号：使用
- 替代 — –
- 省略号：使用
... 替代 …
- 数学符号：保留必要场景，其他替换为文字描述
步骤二：自动化检测
使用 grep 或 Vale 进行预提交检查：
检测非 ASCII 引号
grep -r '[""'']' docs/ || echo "检查通过"
检测 em dash
grep -r '—' docs/ && echo "发现 em dash，请替换为 -"
步骤三：CI 集成
在 GitHub Actions 中添加：
name: Docs Hygiene Check
on: [pull_request]
jobs:
typography:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check for non-ASCII characters
run: |
! grep -rP '[^\x00-\x7F]' docs/*.md
—
常见问题 (FAQ)
Q1: 为什么必须使用 ASCII 字符？UTF-8 不是更现代吗？
UTF-8 支持是必要的，但语义等价的标点符号应优先使用 ASCII。弯引号在视觉上与代码中的直引号几乎相同，但会导致字符串解析失败。技术文档的核心目标是精确可复制，而非视觉美观。
Q2: Mintlify 的 H1 重复问题会影响 SEO 吗？
会。重复的 H1 标签会让搜索引擎困惑于页面主题，可能导致排名下降。同时，脆弱的锚点链接（含特殊字符转义）会降低页面内导航的可靠性，影响用户体验指标。
Q3: 如何批量替换历史文档中的非 ASCII 字符？
推荐使用 sed 或 IDE 的全局替换：
macOS
sed -i '' 's/"/"/g; s/"/"/g; s/'/\'/g; s/—/-/g; s/–/-/g' docs/*/.md
Linux
sed -i 's/"/"/g; s/"/"/g; s/'/\'/g; s/—/-/g; s/–/-/g' docs/*/.md
注意：执行前务必 git diff 确认变更范围。
Q4: OpenClaw 的文档规范是否适用于其他平台？
核心原则（ASCII 优先、单一 H1 来源）适用于任何静态站点生成器，包括 Docusaurus、VitePress、MkDocs 等。具体实现需参考各平台的 frontmatter 处理逻辑。
Q5: 这次更新对终端用户有什么可见影响？
- 文档复制粘贴成功率提升
- 页面锚点链接稳定性增强
- 搜索引擎摘要展示更规范
- 暗色/亮色主题下的字符渲染一致性
—
总结与下一步
OpenClaw 此次文档优化展示了技术写作中的”细节决定体验”原则。92 个字符的变更虽小，却体现了工程团队对开发者体验的极致追求。
你可以立即采取的行动：
1. 审查现有文档的 frontmatter title 与正文 H1 是否重复
2. 在编辑器中启用不可见字符显示（VS Code: editor.renderWhitespace）
3. 将排版检查加入 CI 流程，防止回归
—
相关阅读
—
参考来源
