---
title:  "Workflow: Set up your Help Project"
blurb:  Setting up your help project is the first step in <em>Middlemac</em>’s
        workflow. Understand how to do this setup in this article.
layout: template-logo-medium
---
<%= md_links %>
<%= md_images %>

<%= current_page.data.title %>
==============================

<%= current_page.data.blurb %>

The file `config.rb` has settings which both affect how _Middleman_ operates as
well as how _Middlemac_ builds your help books. **If you follow the _Middlemac_
conventions, there should be no reason to change the _Middleman_ settings.**

When you open `config.rb` in your text editor, at the top you will readily
identify the start of the _Middlemac_ configuration section, which is delimited
by this block at the beginning:

~~~ ruby
################################################################################
#  config.rb
#    Configure Middleman to generate Apple HelpBook containers for multiple
#    targets.
################################################################################
~~~

And terminated by this block at the end:

~~~ ruby
################################################################
# STOP! There's nothing below here that you should have to
# change. Just follow the conventions and framework provided.
################################################################
~~~

## Sections

Because _Middlemac_ is made from several components, its key configuration
is performed in several different blocks. The file is also very well commented,
and the [API Reference][config_ref] contains specific documentation for each
setting.

However the `targets` hash bears explaining.
    
## The `targets` hash explained
  
At first the `targets` option looks complicated in that it consists of nested
hashes, but the format is quite simple to get used to. Each root level item
in `targets` consists of the following items, which are unique for each target.
      
`:CFBundleID`
  : Each help target must have a unique `CFBundleID` that matches a unique
    `CFBundleHelpBookName` in your applications’ `Info.plist` files. This
    pairing is the mechanism by which Mac OS X knows which help bundle belongs
    to which application. If they are not unique, Mac OS X _will_ become
    confused, and your end-users, if they have multiple versions of your product
    installed, will not be very satisfied.
    
`:HPDBookIconPath`
  : If specified a target-specific icon will be used as the help book icon by
    Apple’s help viewer. This path must be relative to the location of the
    `Info.plist` file per Apple’s specification. If `nil` (or not present) then
    the default `shared/icon_32x32@2x.png` will be used.

`:CFBundleName`
  : This value will be used for correct `.plists` and `.strings` setup, and will
    determine final `.help` directory name. All targets should use the same
    `:CFBundleName`. Built targets will be named `CFBundleName (target).help`.
    This is *not* intended to be a product name, which is defined below.
    
`:ProductName`, `ProductVersion`, and `ProductURI`
  : The default templates use these in a prominent way, and they’re also
    available to you using _Middlemac_’s helpers.
 
`:Features`
  : Aside from **targets** the use of **features** can give you fine-grained
    control over what content appears in each target. It’s considered a 
    best-practice to include all of the same features in the hash for each
    target, and specify a boolean (true/false) value for each key, as
    appropriate for your target. _Middlemac_ documentation has four features
    defined.