Phel

Publish help books for your Mac apps

Download Phel Have a Question?

Current version: 0.4

Phel document window

Creating Apple Help Books Is Painful

Adding a help book to your Mac app can reduce the number of support emails you get from customers. But creating a Mac help book is painful. Apple’s Apple Help Programming Guide has been archived and was last updated in 2013. There’s hardly any current documentation for creating help books. Most Mac developers give up in frustration. They add an item to the Help menu that takes people to their website instead of adding a help book.

Phel Simplifies Creating Apple Help Books

Phel is a native Mac app that creates an Apple help book from Markdown files.

Import the Markdown files and any image files into Phel, enter the necessary information for the Info.plist file, and hit the Publish button. Phel returns an indexed help book that you can add to your app’s Xcode project.

Spend less time on customer support and more time improving your app by using Phel to create a help book for the app.

System Requirements

Phel requires a Mac running macOS 12 or later.

Creating a Help Book

When you launch Phel for the first time, you will see either a window for an empty help book or an Open panel. If you see an Open panel, click the New Document button to create a help book.

You can also create a help book by pressing Cmd-N or choosing File > New.

Adding Pages

Phel provides two ways to add pages to your help book: import existing pages and create blank pages. Most of you will import pages.

To import pages into Phel, take the following steps:

  1. Click the Import button in the toolbar.
  2. Select the files you want to import from the Open panel.
  3. Click the Open button.

To add a blank page to your help book, click the Add button below the page list. A sheet opens.

Enter the name for the page in the text field. Click the Add Page button to finish adding the page.

Entering Help Book Info

An Apple help book requires its own Info.plist file. When you publish a help book in Phel, it generates the Info.plist file.

Take the following steps to enter the help book info:

  1. Click the Book Info button in the toolbar.
  2. Enter the information for your app in the sheet that opens.
  3. Click the Done button when you are done.

Replace any instance of My App in the text fields with the name of your app. Replace CompanyName with the name of your company.

Adding Images

Importing all the help book’s images at once is the easiest thing to do. The image browser is on the right side of the window. To import images into Phel, take the following steps:

  1. Click the Import button in the image browser.
  2. Select the files you want to import.
  3. Click the Open button.

If you need to insert Markdown image tags into your help book’s text, select an image from the list in the image browser, and click the Insert button.

Publishing the Help Book

Take the following steps to publish your help book:

  1. Click the Publish button in the toolbar.
  2. Choose a location to save the help book.
  3. Click the Publish button.

Publishing the help book also indexes the book so people can search inside the help book.

Adding the Help Book to Your App

After you publish your help book, you must add it to your app. You must do the following tasks to add the help book to your app:

  • Add the help book to your Xcode project.
  • Add help book entries to your app’s Info.plist file.
  • Register the help book

Add Help Book to Xcode Project

When you add the help book to your project, Xcode asks if you want to create groups or folder references. Choose folder references. By selecting folder references, Xcode will copy the help book to the app bundle when building your project.

Add Help Book Entries to Info.plist

Start by accessing your app’s Info.plist file. Take the following steps:

  1. Select your project from the left side of the project window to open the project editor.
  2. Select your app target from the target list on the left side of the project editor.
  3. Click the Info button at the top of the project editor.

The Custom macOS Application Target Properties section is where you add the help book entries. You must add two entries.

First Entry

  • Key: Help Book identifier
  • Type: String
  • Value: The help book’s bundle identifier (com.CompanyName.AppName.Help)

Second Entry

  • Key: Help Book directory name
  • Type: String
  • Value: The name of your published help book file

Include the .help extension when entering the name of your help book file.

Register the Help Book

To register your help book, run your app and open the help book from the Help menu.

Troubleshooting

Saving the Help Book

When you save a book initially, there is a File Format menu in the Save panel. Make sure the file format is Help Book, which should be the default. If you choose another file format, you won’t be able to open the help book the next time you launch Phel.

The File Format menu is part of a limitation in SwiftUI, as detailed in the following Apple forums thread:

Prevent Save Panel in SwiftUI Mac app from saving as file type my app exports

Help Book Not Appearing

If you run your app from Xcode and open your help book from the Help menu, you may get the following page in the Help Viewer app:

help viewer missing content

The cause of this error is the help book not being registered in the Help Viewer app. To work around this issue, you must run your app from the Applications folder.

In Xcode choose Product > Show Build Folder in Finder to show your app bundle in the Finder. Copy the app bundle to the Applications folder. Run the app from the Applications menu, and you should be able to view the help book from the Help menu.

Current Bugs and Limitations

  • There is no localization of help books.