I just open-sourced my Help Compiler, a self-contained command-line tool to build HTML help from simple plain-text source. I’m already using it to compile TimeStory’s user guide for both Web and in-app help. If you’re maintaining a Mac app with a help system, I think you might find it useful.
HC replaced my older Jekyll-based system, solving several problems or annoyances I’d had, while simplifying my build and removing the dependency on Jekyll and Ruby. A few key features:
- A Mac app’s user guide will frequently reference its main menu. HC has built-in syntax to look up a menu item by its action selector from a NIB file, validating it and extracting the correct menu path. This makes sure the HTML stays updated as when the menu tree changes.
- Cross-linking is very simple. Every section gets an ID, which HC ensures is unique, and links reference those IDs, which HC validates and for which it generates the correct relative URL. There’s no way to manually type in a URL, and no way to generate a broken link.
- It’s common for links to just reference the target section’s title, as in
“Learn more in Customizing Event Icons”. in HC, you can use a
double-bracket shorthand, writing
Learn more in [[point-icons]], and it will look up thepoint-iconsID, generate the link, and copy its title for you. - HC uses
NSSpellCheckerto run everything through macOS’s built-in spellchecker. - If you pass the
-eoption, HC will fail with a detailed error report if it finds any spelling mistakes, unknown link IDs, unknown menu items, markup syntax errors, etc. I use-ein my prerelease build script, so I never generate a numbered build with any of those errors in Help. And, yeah, unlike Markdown, HC has the concept of markup syntax errors. - HC outputs structured HTML. Specifically, sections and their headers are
grouped into a hierarchy of
<section>elements, and images (which are always block-level in HC) are wrapped in<figure>elements with optional captions.
There’s more. Despite all that, most of your text looks like Markdown. Check
out the README for full documentation on syntax. The biggest limit
you’ll probably hit is that I hardcode most of the output HTML structure (e.g.
the contents of <head>), though the CLI lets you inject extra HTML or set
the stylesheet name; I’m very open to fixing that if other folks start using
it.
For now, HC is just a source release (under the MIT license). It’s built with
SwiftPM, so download the release or clone the repo, run swift build, and
find the compiled tool in .build/debug. I’d love to hear from anyone who
tries it out!