——
OpenClaw 文档规范更新：5个页面如何修复98个排版问题？
文档质量是开源项目专业度的直接体现。本文深入解析 OpenClaw 最新的一次文档优化提交——在 5 个核心页面中修复 98 个排版字符问题，并消除重复的 H1 标题。这次更新不仅提升了文档的可读性，更为 AI Agent 插件开发者提供了清晰的规范参考。
—
为什么排版规范对技术文档至关重要
技术文档的排版质量直接影响开发者体验。不规范的字符（如弯引号、非标准连字符）可能导致：
- 搜索失效：特殊字符干扰代码片段的复制粘贴
- 渲染异常：不同平台对 Unicode 字符的支持不一致
- 自动化困难：CI/CD 流程中的文本处理工具可能报错
OpenClaw 作为 AI Agent 插件开发平台，其文档需要支持多种自动化场景，包括 SDK 生成、测试用例提取等。因此，建立严格的 typography hygiene（排版卫生）规范成为必然选择。
—
本次更新的核心改动
修复98个非ASCII排版字符
根据 docs/CLAUDE.md 中定义的 heading and content hygiene rules，本次提交将以下字符统一替换为 ASCII 等价形式：
| 非标准字符 | ASCII 替换 | 使用场景 |
|———–|———–|———|
| ' (弯单引号) | ' (直单引号) | 代码字符串、所有格 |
| " (弯双引号) | " (直双引号) | 代码引用 |
| — (em dash) | -- 或 - | 范围表示 |
| – (en dash) | - | 数值范围 |
| ‑ (非断连字符) | - | 普通连字符 |
受影响的5个文档页面
查看具体修改分布
docs/plugins/sdk-migration.md # 20 个字符
docs/help/testing.md # 20 个字符
docs/automation/tasks.md # 20 个字符
docs/plugins/sdk-channel-plugins.md # 19 个字符
docs/channels/yuanbao.md # 19 个字符 + H1 修复
消除重复的 H1 标题
在 docs/channels/yuanbao.md 中，移除了正文内的 # Yuanbao 标题。原因是 Mintlify 文档平台会自动从 frontmatter 渲染页面标题：
---
title: "Yuanbao"
description: "Yuanbao 渠道配置指南"
---
正文内容从这里开始...
这种重复会导致：
- 搜索引擎抓取到两个 H1，影响 SEO
- 屏幕阅读器重复朗读标题
- 目录结构显示异常
—
如何在项目中实施排版规范
第一步：配置自动化检测
在 OpenClaw 项目中，可以通过 GitHub Actions 添加排版检查：
.github/workflows/docs-lint.yml
name: Documentation Lint
on:
pull_request:
paths:
- 'docs/**'
jobs:
typography-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check for curly quotes
run: |
# 检测弯引号
if grep -r "[\'\"\"'']" docs/ --include="*.md"; then
echo "❌ 发现非标准引号，请替换为 ASCII 等价字符"
exit 1
fi
- name: Validate H1 uniqueness
run: |
# 确保每个 markdown 文件只有一个 H1
for file in docs/*/.md; do
h1_count=$(grep -c "^# " "$file" || true)
if [ "$h1_count" -gt 1 ]; then
echo "❌ $file 包含 $h1_count 个 H1 标题"
exit 1
fi
done
第二步：本地预提交钩子
使用 Husky 和 lint-staged 在提交前自动修复：
安装依赖
npm install --save-dev husky lint-staged
配置 package.json
{
"lint-staged": {
"docs/*/.md": [
"node scripts/fix-typography.js",
"git add"
]
}
}
第三步：自定义修复脚本
// scripts/fix-typography.js
const fs = require('fs');
const path = require('path');
const REPLACEMENTS = [
{ pattern: /[\u2018\u2019]/g, replacement: "'" }, // 弯单引号
{ pattern: /[\u201C\u201D]/g, replacement: '"' }, // 弯双引号
{ pattern: /\u2014/g, replacement: '--' }, // em dash
{ pattern: /\u2013/g, replacement: '-' }, // en dash
{ pattern: /\u2011/g, replacement: '-' }, // 非断连字符
];
function fixTypography(content) {
return REPLACEMENTS.reduce(
(text, { pattern, replacement }) => text.replace(pattern, replacement),
content
);
}
// 处理指定文件
const filePath = process.argv[2];
const content = fs.readFileSync(filePath, 'utf8');
const fixed = fixTypography(content);
if (content !== fixed) {
fs.writeFileSync(filePath, fixed);
console.log(✅ 已修复: ${path.basename(filePath)});
}
—
Mintlify 平台的最佳实践
OpenClaw 使用 Mintlify 作为文档托管平台。理解其渲染机制对避免标题重复至关重要：
Frontmatter 优先原则
Mintlify 的页面标题解析优先级：
1. title frontmatter 字段
2. 第一个 H1 标题（# Title）
3. 文件名（转换为标题格式）
因此，推荐始终使用 frontmatter 定义标题，正文不再包含 H1：
---
title: "SDK 迁移指南"
description: "从旧版 SDK 迁移到 OpenClaw 新架构的完整步骤"
---
准备工作
内容从这里开始，使用 H2 作为最高层级...
验证工具
本地预览时检查标题结构
npx mintlify dev
访问 http://localhost:3000 确认渲染效果
—
FAQ：常见问题解答
Q1: 为什么必须使用 ASCII 字符，Unicode 不是更标准吗？
Unicode 排版字符在印刷场景更美观，但技术文档的核心需求是可复制性和一致性。ASCII 字符确保代码片段在任何编辑器、终端、自动化工具中表现一致，避免 “智能引号” 导致的语法错误。
Q2: 如何批量检查现有文档的排版问题？
可以使用 grep 结合 Unicode 范围快速扫描：
查找所有非 ASCII 标点
grep -rP '[^\x00-\x7F]' docs/ --include="*.md" | \
grep -E '[\u2018-\u201D\u2013\u2014\u2011]'
或集成 Vale 文档检查工具，自定义样式规则。
Q3: Mintlify 的 H1 重复会影响 SEO 吗？
是的。搜索引擎（如 Google）将 H1 视为页面主题的核心标识。多个 H1 会稀释关键词权重，可能导致排名下降。Mintlify 的 frontmatter 机制正是为了避免这种问题。
Q4: 这次更新对 OpenClaw 插件开发者有什么影响？
开发者无需修改现有代码，但建议参考更新后的文档风格编写插件 README。一致的排版规范有助于 OpenClaw 自动化工具正确解析文档，生成准确的 SDK 参考和 API 文档。
Q5: 如何为我的项目引入类似的文档规范？
1. 创建 CLAUDE.md 或 CONTRIBUTING.md 明确规范
2. 配置 CI 检查阻止不合规提交
3. 使用编辑器插件（如 VS Code 的 Smart Typography）自动转换
4. 定期运行批量修复脚本维护存量文档
—
总结与下一步
本次 OpenClaw 文档更新展示了专业开源项目的细节追求：通过 98 个字符的精准替换和 1 个 H1 的移除，提升了文档质量、自动化兼容性和搜索可见性。
关键收获：
- ✅ 建立
docs/CLAUDE.md作为排版规范源文件 - ✅ 利用 Mintlify frontmatter 避免标题重复
- ✅ 将文档检查集成到 CI/CD 流程
推荐行动：
- 查看 OpenClaw 文档 了解完整规范
- 参考 SDK 迁移指南 更新你的插件
- 加入 OpenClaw 社区 参与文档改进
—
相关阅读
—
