Jekyll-Apple-Help is a Jekyll template and Xcode build system that makes it easy to author and build Mac OS X Help Books. Add Help to your Mac app, and start authoring in Markdown within minutes. The resulting Help has the same look & feel as Apple's Yosemite apps.
Try out the Demo Site.
When recently helping develop a Mac App (Xynk), I wanted to make some how-to documentation available through Apple's help system. Should be some simple HTML, right? Well, as Apple Help veterans know, the help developer documentation is byzantine and the tools are idiosyncratic. How to simplify help for the indie developer?
Fundimentally, Mac OS X's Apple Help Books are static web sites and Jekyll is an excellent static site generator, so the two fit naturally. In particular, Jekyll's recently added Collections feature is perfect for wrangling help topics. Add some layouts, plugins, and build-glue and you get Jekyll-Apple-Help.
- Use Markdown to write help topics
- Xcode integration
- Automatic and flexible navigation menu
- Automatic help index generation
- Styled like Yosemite's help
- Supports Multi-lingual help
Optional: fswatch for auto-refresh via jekyll-server.command
The JekyllHelp template is designed for easy installation into a typical Xcode project. By default, the template's Info.plist expects the project and app to have the same name (e.g. MyApp.xcodeproj builds MyApp.app).
In the following, substitute your app/company for "MyApp"/"com.mycompany".
-
Select File > New > Target...
-
Select Bundle template from OS X > Frameworks & Libraries
-
Enter the settings:
- Product Name: MyAppHelp
- Bundle Extension: help
-
Replace Xcode-generate MyAppHelp folder with JekyllHelp (renamed to MyAppHelp)
-
Update Bundles identifier to
com.mycompany.* -
Add a Run-Script Build-Phase with the script:
/usr/bin/make -C "$(dirname "$PRODUCT_SETTINGS_PATH")"
Now the MyAppHelp target should build, creating the product MyAppHelp.help
- Add target MyAppHelp to MyApp's target dependencies (Build Phases > Target Dependencies)
- Add product MyAppHelp.help to app target (via File Inspector)
- Add to MyApp target Info properties:
- Help Book Identifier:
com.mycompany.$(PROJECT_NAME:rfc1034identifier).help - Help Book directory name:
$(PROJECT_NAME)Help.help
- Help Book Identifier:
Finished. Now run your app and use the Help menu to open/search help.
Basic authoring only involves the following files in the bundle:
- JekyllHelp
- book-icon.png
- _English.lproj
- index.md
- topic-1.md
- topic-2.md
The Help-Book icon file book-icon.png is displayed on the help title page and in topic page headers. Typically it is just a copy of the app icon. It should be large (~512px) to accomidate retina displays.
🚧
Sort topics by including a line like this in the front matter of your topic page: order: 3. Number each one as you would like it to appear within its group.
To order groups, open the index.md file and add your group names to the group_order hash in this format:
group_order: {"Group Name": 1, "Another Group": 2}
Each help topic is a single Markdown file in a language collection folder (e.g. _English.lproj). The only required Front Matter variable is a title. A 'hello world' topic:
---
title: Hello World
---
Welcome to JekyllHelp.
Help Topic Variables:
- title
- description
- keywords
- order
- robots
A more typical Front Matter example with variables for description, keywords and ordering:
---
title: Keyboard Shortcuts
description: Quickly accomplish many tasks using keyboard and other shortcuts.
keywords: keypress, accelerators, cheat codes
order: .INF
---
...topic content...
A new language is added by creating a new langauge collection folder (e.g. _Japanese.lproj). Language collections must be registered in _config.yml. Some common language are registered in the default configuration (EJD-FIGS).
JekyllHelp's Makefile will generate a help index for every *.lproj in the help bundle.