如何能够创建类似 macOS 官方文档这样的 Help Book？

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 935 天前的主题，其中的信息可能已经有所发展或是发生改变。

排版很漂亮，旁边的树形导航也很好用，还可以全文搜索。

树形

macOS

排版

book

11 条回复 • 2022-05-10 20:13:06 +08:00

lxy42

2022-05-07 18:42:49 +08:00 via Android

想起了 Windows 下 chm 格式的文档，不知道能不能找到类似的原文件

RIDESU

2022-05-07 19:38:58 +08:00

其实 PDF 完全能够复现，只需要添加好「大纲」（有的软件叫「书签」），用预览 app 打开跟这个几乎就是一模一样了

wzcloud

2022-05-07 19:51:31 +08:00

用 gitbook?

SimonOne

2022-05-07 20:00:13 +08:00

https://wiki.freepascal.org/Add_an_Apple_Help_Book_to_your_macOS_app
是这个吗？

SimonOne

2022-05-07 20:05:10 +08:00

https://github.com/chuckhoupt/jekyll-apple-help

jdjingdian

2022-05-07 20:15:42 +08:00

我也想搞一个这个，但没找到资料，就写了一个 view 专门用来放手册的内容，不过排版丑的一批，求大神们指路

SimonOne

2022-05-07 20:34:54 +08:00

@jdjingdian #6 为啥我 google 一下“create macos Help Book”就全是资料嘞 😂

Tianao

2022-05-07 20:35:53 +08:00

GitBook 吧。

aptx4689

2022-05-07 22:32:27 +08:00

com.apple.helpviewer
也许可以查一下这个东西

jdjingdian

2022-05-09 10:04:52 +08:00

@SimonOne 我以前搜的关键词是 handbook 和 user guide🌚

zhengjian

2022-05-10 20:13:06 +08:00

抓包看了一下，是 Help Viewr App 通过网络数据渲染的。App 在 `/System/Library/CoreServices/Help Viewer.app`，即 #9 说的 com.apple.helpviewer 。

以这本帮助手册为例：

1. 获取手册信息，包含手册的基本信息和目录结构等。

```
https://cds.apple.com/content/services/book?platform=mac&pOSv=12.3&product=mac-help&productVersion=12.3&locale=zh-Hans
```

树形导航是解析其中的目录结构生成的。

2. 当点击某一文章时，会获取文章详情。

```
https://cds.apple.com/content/services/lookup?platform=mac&pOSv=12.3&product=mac-help&productVersion=12.0&locale=zh-Hans&bookid=5e2077d8bc16862b7fd64110d1406f84&topicid=MH43558

```

文章内容是 html 字符串，其中的图片都是网络资源。

CSS 是 `https://support.apple.com/clientside/build/app-apd.css`

全文检索是在本地实现的，在手册信息中 `miscAttributes` 包含了几个索引文件，比如：

```
https://help.apple.com/assets/61D4C1B5425F2576373C512A/61D4C1B7425F2576373C5132/zh_CN/search.helpindex

https://help.apple.com/assets/61D4C1B5425F2576373C512A/61D4C1B7425F2576373C5132/zh_CN/search.cshelpindex

https://help.apple.com/assets/61D4C1B5425F2576373C512A/61D4C1B7425F2576373C5132/zh_CN/searchTree.json

```

搜索了下应该是用 `hiutil` 创建的索引文件。

以上只是手册数据来源，我不熟悉 Apple 平台开发，App 的实现上不太了解。

参考资料：

1. https://apple.stackexchange.com/questions/271501/what-is-hiutil-and-why-is-it-sucking-up-my-cpu

2. 终端 `man hiutil`

3. `.helpindex` 文件格式 https://developer.apple.com/documentation/latentsemanticmapping

这个手册的在线版在 https://support.apple.com/zh-cn/guide/mac-help/welcome/12.0/mac

----

另外，我认为 Apple 的这种在线帮助手册也非常好看：

https://help.apple.com/app-store-connect/#/

并且，这个全文检索也是在浏览器本地完成的，通过一个分词后的索引文件。

```
https://help.apple.com/app-store-connect/zh_CN.lproj/searchTree.json
```