OpenClaw 文档规范更新：5个页面如何修复98个排版问题？

——

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 流程

推荐行动：

—

相关阅读

—

参考来源