如何制作适配Dash/DevDocs app的可用docset文档集

前置准备 #

• 安装Dash官方docset生成工具：打开Dash偏好设置，进入Docsets标签页，点击Contribute Docs按钮会自动安装全套生成依赖，无需额外下载第三方工具
• 提前准备好目标文档的离线源：
  • GitHub CLI Manual：本地已安装GitHub CLI的前提下，执行gh help --all > gh_raw.md可拉取全量命令说明，也可直接拉取GitHub CLI官方仓库的docs目录获取结构化的markdown源文件
  • WordPress Codex：用静态站点爬取工具抓取Codex全站点静态文件，爬取时过滤评论区、广告位、用户编辑日志等无关内容，仅保留正文文档

通用制作流程 #

所有适配Dash/DevDocs的docset都遵循固定结构，按以下步骤操作即可：

1. 搭建标准docset目录结构，层级不能随意修改：

[Docset名称].docset/
└── Contents/
    ├── Resources/
    │   ├── Documents/  # 存放所有离线文档文件（html/md等可渲染格式）
    │   └── docSet.dsidx  # 全文搜索索引数据库，是Dash实现快速检索的核心
    └── Info.plist  # docset基础配置文件

2. 配置Info.plist核心字段，缺省会导致docset无法识别：

• CFBundleIdentifier：docset全局唯一标识，例如github-cli-manual、wordpress-codex
• CFBundleName：Dash文档列表内显示的名称，例如GitHub CLI Manual
• DocSetPlatformFamily：快捷检索触发前缀，例如设置为gh后，在Dash搜索框输入gh:即可限定仅在该文档内检索
• isDashDocset：固定值为true

3. 生成搜索索引文件docSet.dsidx：直接用SQLite创建数据库，固定表结构如下：

CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);

索引录入规则：

• 针对GitHub CLI Manual：将所有一级命令、子命令标记为Command类型，参数、可用环境变量标记为Option类型，path字段填写对应文档在Documents目录下的相对路径
• 针对WordPress Codex：将函数、钩子、类、教程条目分别标记为Function/Hook/Class/Guide类型，废弃条目可在name字段标注[Deprecated]前缀，搜索时会直接提示

4. 文档内容适配调整：

• 所有文档内的资源引用、交叉跳转全部改为相对路径，避免离线状态下加载失败
• 移除所有外链、动态脚本、第三方统计代码，保证纯离线可正常渲染
• 代码块添加对应语言标记，Dash会自动做语法高亮

两类文档的专属优化 #

GitHub CLI Manual 适配 #

• 转换markdown源为html时保留命令层级：子命令、参数、使用示例、注意事项分块排版
• 常用命令组合示例单独添加索引，方便快速检索

WordPress Codex 适配 #

• 爬取的静态文件按内容分类存放：函数参考、钩子参考、主题开发、插件开发、版本兼容说明分别建子目录
• 版本兼容要求、弃用提示提取为索引附加信息，搜索结果页可直接看到对应说明，无需点进详情页

导入验证 #

• 双击生成好的.docset文件，Dash会自动完成导入
• 验证项：
  • 断网状态下可正常打开所有文档页面，无丢失资源、加载失败问题
  • 搜索命令、函数等关键词可精准命中对应条目，无错链、死链
  • 页面内跳转、代码块渲染、锚点定位功能正常
• 适配DevDocs的话，将生成好的docset放入DevDocs的本地文档存储目录，重启应用即可识别加载

内容的提问来源于stack exchange，提问作者Devin Schumacher