How to best author a Apple Helpbook for a macOS app?

Question

macOS apps, e.g. Photos.app, provide a help panel to the user

Is there a way to author such a Help Book in your own macOS app? Is there a way to at least provide a toolbar to be used for a table of contents?

I am asking specifically about the UI and all the user interactions. Not how to generally create and register a helpbook.

Update

Here is what I’ve been able to find/gather/learn from others. A Help Book appears to run on a separate app/process called “HelpViewer”. Any Apple macOS app displaying a help makes use of a DDMViewerController that isn’t public.

There is an “app.css” and an “app.js” being used by the Apple macOS app “index.html” of the Apple Help Book. The Javascript one manipulates the DOM to create the “show-hide” link that toggles the Sidebar. Haven’t been able to find how to instruct HelpViewer to use a sidebar.

There is a WWDC talk from back in 2014, “Introducing the Modern WebKit API” that talks about “User Scripts” and “Script Messages” which allow communication between a Webview and Cocoa. https://developer.apple.com/videos/play/wwdc2014/206/

AFAICS, there is no way to have HelpViewer display a custom view or have a sidebar. My guess is that you would have to implement everything yourself. That is an NSSplitViewController, NSToolbar, NSOutlineView, any Javascript alongside the “app.css” to get the look and feel.

Answer 1

Currently it's not possible to implement the sidebar as shown in the Maps and other built-in macOS applications from 10.13 onward.

Versions of macOS from 10.10 (built-in applications) implement sidebar navigation with HTML and JavaScript, and Apple Help Viewer itself offers a window.HelpViewer object with some hooks that enable/disable the Help Viewer's table of contents button. Once enabled, it will callback into your own JavaScript where you can show/hide TOC via CSS or JS.

From approximately 10.10, Apple's non-built-in applications have also been using this technique. For example, iTunes and Xcode help both do this.

From 10.13, macOS has a newer version of Help Viewer that provides an actual Cocoa-native table of contents and windows splitter, as well as some new properties on window.HelpViewer; presumably these can be used to enable/disable the Cocoa sidebar and populate the TOC, but these are undocumented and I'm not sure anyone outside of Apple has been able to reverse-engineer this functionality yet.

And in any case, it wouldn't work if you offer Help Books to pre-10.13 users, and the use of undocumented API's restricts applications from the App Store (although, I'm not certain that Apple scans Help Book JavaScripts for API usage as part of their review).

(There are also a lot of other changes to how Apple's built-in application Help works now, too, but that's another topic entirely.)

Thus the answer for now is we can't, or shouldn't, or just don't know how. Alternatives include using something like using jekyll-apple-help (no affiliation) or Middlemac 3 (my project), or just rolling your own.

For those interested in knowing how Apple does it, I've documented a lot of it here (disclosure: link to my own website).

Answer 2

I'm not sure whether Apple's current applications still use it, but there is a very old API on macOS for Help Books. Apple has documentation on how to create them and some introduction. In short: Help books are standard HTML files with additional proprietary anchors. Those anchors are accessible via the class NSHelpManager, e.g. to open the help book at a specific page.

See also this question.