---
title: Apple Help Book Features
blurb: View examples of the features provided by modern Apple Help Books.
---
<%= md_links %>
<%= md_images %>
<%= current_page.data.blurb %>
Universal Deployment
--------------------
Modern Apple Help Books are designed to look and work great in Apple Help
Viewer, but also look great when served to a browser on the desktop or mobile,
such as Apple does with their documentation.
![Universal Deployment Screenshot][apple_help_features_universal]
The Help Book, when used in Apple Help Viewer or served to a browser has all
of the same features that you’d expect in the Help Viewer:
- The Help Book title is displayed as the window title in Help Viewer, and
as a top banner in a browser.
- The Apple Help Viewer window title bar is ready to execute a search, and
when in a browser, search function is available with the button in the
page banner.
A key difference _does_ exist when searching in Apple Help Viewer versus
the web browser. Help Viewer uses a binary search index file generated by
the `hiutil` command, and the JavaScript that runs the browser version uses
a file in JSON format representing a prefix tree (or trie). _Middlemac_
covers you in both of these cases, however!
{: .note .callout}
- The Table of Contents button is enabled in Apple Help Viewer, and a Table
of Contents button is added to the page banner in the browser. In both
cases, a navigation menu is revealed with support for flat or nested Help
Book structures.
All in all, serving a modern Help Book to a web browser delivers all of the
experience of a Help Book in Apple Help Viewer.
Asides
------
“Asides” are loaded via AJAX from another file into a popup element on the
current page, and provide a description, example, or some other contextual
information without having to load a new page.
![Example Aside Screenshot][apple_help_features_aside_example]
Would you like to access an example of
<%= link_to "an aside", "aside_description.html", :aside => true %>?
Activate the specially decorated link to see one in action.
Copyright Information
---------------------
You can provide a copyright message via your [`config.rb`][config_ref] file,
which Apple’s help system will use to display in certain circumstances:
- When viewed served to your browser, each page of your project will include
your copyright statement.
![Copyright Footer Example][apple_help_features_copyright_footer]
- When printed from Apple Help Viewer, this statement will be used as a footer
for each printed page.
- This message will be displayed on your Help Book’s [landing page][en.lproj]
when served to a browser, and, if you also have a topic page with a
[frontmatter][frontmatter] `categories` entry containing `copyright`, then
this copyright message on the landing page will be displayed as a link to
this specified page.
![Landing Page Links][apple_help_features_landing_links]
Navigation
----------
Apple provides an automatic table of contents based on the sections and topic
pages that you define, which normally appears on the left (for Left to Right
locales) or right (for Right to Left locales) side of the page content.
![Navigation Sidebar Example][apple_help_features_navigator]
In the Help Viewer, this table of contents can be revealed or hidden using the
Help Viewer’s TOC button in the window title bar, or with the
**Show Topics** (or **Hide Topics**) link that will be be added to the Help
Book’s [landing page][en.lproj].
When viewing the Help Book served to a web browser, the **Show Topics** (or
**Hide Topics**) link will not appear. However, the TOC can be revealed or
hidden via a TOC button that will appear in the banner of the page.
Style Sheets
------------
With a few exceptions described elsewhere in this documentation, all of the
styling is provided by Apple via the `apple.css` stylesheet. Because Apple
Help Books generally do not show source code, the `github.css.scss` style
sheet supplements Apple’s styles, and the `middlemac.css.scss` style sheet
corrects a couple of issues with Apple’s styles, as well as provides a simple
alternative for creating Apple’s [tips paragraphs][implement_features].
Tasks
-----
Apple currently uses “tasks” in many of its modern Help Books, and these are
relatively simply to implement with the [`helpbook_task`][implement_features]
helper.
Single tasks are always displayed in the expanded state, but when multiple tasks
are on the same page, like here, they have working disclosure triangles to
reveal them.
Make sure you provide unique id’s to the tasks, because Apple’s help system
keeps track of which ones are revealed or hidden in between page visits.
<% helpbook_task "task1", "Expand this task to see what content it contains", :markdown => true do %>
<%= lorem.paragraphs 2 %>
<% end %>
<% helpbook_task "task2", "This task indicates the answer to the question of life" do %>
The generally accepted answer to this query is **forty-two**.
<%= lorem.paragraphs 2 %>
<% end %>
<% helpbook_task "task3", "Perform this third task" do %>
Apple’s practice is to nest `` elements within `` elements, and
for Apple’s CSS to work properly, this practice should be adhered to.
_Middlemac_ makes this easy for you by doing this automatically when the
[`image_tag`][helpers] helper is used, and when markdown reference format
images are used, such as here.
![Icon loaded with the Markdown reference format][icon_256x256]
<% end %>
Tips
----
Modern Apple Help Books often show tips with a colorful icon to draw your
attention.
Generally tips are something related to the main content of your article,
but not necessarily part of the narrative. They might be used to point out
information that’s not so obvious to your user.
{: .tip}
Although Apple doesn’t use the following tip styles, _Middlemac_ offers them
as an extension because they come in useful, like tips, but convey different
semantics to your users.
Although I couldn’t find any **warning** examples in Apple’s help, it’s
something that’s sure to be needed by other developers, and so imitating
Apple’s **Tip** style gives _Middlemac_ access to simple warnings, too.
{: .warning}
Notes have a use case similar to tips, but with the intention of providing
additional information that is more educational, rather than pointing out a
way to do something.
{: .note}
Standard See Also
-----------------
Apple’s Help Books have a standard format for **See Also** sections of its
content pages. _Middlemac_’s layouts will automatically provide the proper
HTML structure when you provide a `:seeAlso` block in any of your help pages.
![See Also example][apple_help_features_see_also]
Apple’s JavaScript even recognizes when links are internal or external, and
opens new tabs or windows as appropriate.
A sample **See Also** section appears at the bottom of this page.
<% content_for :seeAlso do %>
<%= link_to 'See Also article on Wikipedia', 'https://en.wikipedia.org/wiki/See_also' %>
<%= link_to 'Implement Apple’s Help Features', 'compose_project/implement_features.html' %>
<%= link_to 'Help Book Landing Page', 'index.html' %>
<% end %>
Other Features not Available on this Page
-----------------------------------------
### Chapter Headings
You can’t see any chapter headings on this page, because it’s a root level
page. However if you look at page within a section, such as the
[Set Up Middlemac][setup] page in the **Get Started** section, you will
see that the chapter/section name is automatically added to the top of your
page, before the title.
The example below, from iTunes’ help, shows a page with a chapter heading from
its “Get Music, Video, and More” section:
![Sample Chapter Heading][apple_help_features_chapter_heading]
### Languages
In addition to the **Copyright** and **Navigation** features described above,
the [Help Book Landing Page][en.lproj] also provides an interface to switching
languages when your Help Book is served to a web browser. Feel free to head
back to the [landing page][en.lproj] to switch the language to Spanish for a
demonstration of this feature.
![Language Chooser Example][apple_help_features_language_chooser]
Within Apple Help Viewer, this feature does not exist, as Help Viewer chooses
the locale for you automatically based on your operating system settings.
### Next and Previous Page Links
Although disabled by default, you can change the `show_previous_next` setting
in [setup][setup] to `true` so that your Help Books will automatically
include Apple-style “next page” and “previous page” navigation buttons at the
bottom of each of your content pages. Because Apple itself does not use this
feature, it has not been enabled by _Middlemac_.
### Title Icons
When viewed in Apple Help Viewer, the help icon is automatically inserted
before the page title headline. For some reason, Apple doesn’t do this when
your content is viewed served to a browser.
![Title Icons Example][apple_help_features_title_icons]
Although this is consistent with Apple’s own practices, examining the source
reveals that the icon is served as part of the page, but merely hidden via
Apple’s CSS. Given that this is what Apple wants to do, choosing to override
this behavior via CSS is an exercise left to the user.