1. 什么是 Dash

Dash 是 macOS 上常用的离线开发文档工具。它把不同语言/框架的文档打包成 docset，本地检索和跳转都很快，也可以和编辑器联动使用。

我们可以简单理解：Dash = 本地文档阅读器，docset = 可安装的文档包。 这篇文章要解决的就是如何把任意 HTML 文档做成 Dash 可安装的 docset。 如果文档是 Sphinx/Javadoc 这类“已知格式”，可以直接用对应工具链。 如果是 Docusaurus、MkDocs 静态站或自己抓下来的 HTML，dashing 更直接。

2. 两条路线怎么选

Kapeli 官方给了两条主线：

  1. 已有专用生成器：比如 Sphinx/PyDoctor、Javadoc、GoDoc 等，优先用专用工具。
  2. Any HTML Documentation：手工/脚本生成 docset（目录 + Info.plist + docSet.dsidx）。

对于“任意 HTML”，官方也明确提到可以用 dashing 自动生成，省掉很多手工索引工作。

3. 先准备离线 HTML（保持原始结构）

以抓取 https://playwright.dev/python/ 为例：

1
2
3
4
5
6
7
8
9
wget \
  --mirror \
  --convert-links \
  --adjust-extension \
  --page-requisites \
  --no-parent \
  --domains=playwright.dev \
  --accept-regex '/python/' \
  https://playwright.dev/python/

验证本地 HTML 是否可正常浏览：

1
python -m http.server 8000

访问 http://localhost:8000，确认链接、样式、页面层级都正常。

4. 安装 dashing

1
brew install dashing

dashing 的核心机制是：用 CSS Selector 从 HTML 中抽取索引项，再映射到 Dash 的类型（Class/Function/Guide 等）。

5. 用 dashing 生成 docset

进入文档根目录后执行：

1
dashing create

会生成 dashing.json 模板。最小可用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "name": "Playwright Python",
  "package": "playwright-python",
  "index": "index.html",
  "icon32x32": "icon.png",
  "externalURL": "https://playwright.dev/python/",
  "selectors": {
    "h1 a": "Guide",
    "h2 a": "Section",
    "code a": "Function"
  },
  "ignore": [
    "Next",
    "Previous"
  ]
}

然后构建：

1
dashing build playwright-python

生成目录通常是 playwright-python.docset。

6. Dash docset 的最低结构（官方）

如果你不走 dashing，而是手工构建，Kapeli 官方要求至少有：

  1. 目录结构：
1
2
3
4
5
6
7
<name>.docset/
  Contents/
    Info.plist
    Resources/
      docSet.dsidx
      Documents/
        ...html
  1. docSet.dsidx 里有索引表：
1
2
CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);
  1. 插入索引数据：
1
INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('name', 'type', 'path');

type 需使用 Dash 支持的 entry type（如 Class、Function、Method、Guide 等）。

7. 常用增强项（Info.plist）

Kapeli 文档里这几个键最实用：

  1. 设置打开 docset 时默认首页：
1
2
<key>dashIndexFilePath</key>
<string>index.html</string>
  1. 配置在线回跳（本地页找不到时可跳线上）：
1
2
<key>DashDocSetFallbackURL</key>
<string>https://playwright.dev/python/</string>
  1. 允许外部 JS（按需开启）：
1
<key>isJavaScriptEnabled</key><true/>
  1. 全文检索默认开启：
1
<key>DashDocSetDefaultFTSEnabled</key><true/>

另外，根目录加 icon.png（16x16 或 32x32）可自定义图标。

8. 安装到 Dash 与排错

  1. 把生成好的 .docset 导入 Dash。
  2. 若你改了 Info.plist（如首页、JS、FTS 配置），Kapeli 建议先移除再重新添加 docset。
  3. 如果搜索结果为空，优先检查：
  • selectors 是否匹配到实际 HTML
  • ignore 是否误伤
  • type 是否在 Dash 支持列表内
  • path 是否是相对 Documents/ 的正确路径

9. 总结

“任意 HTML 文档做 Dash 离线文档”的最省心路径是：
wget 镜像文档 -> dashing create + 调 selectors -> dashing build -> Dash 导入验证。
需要高级能力时，再按 Kapeli 官方规范补 Info.plist 和索引策略。

10. 参考链接：