middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/050_structure/040_breadcrumbs.html.md.erb

@@ -0,0 +1,43 @@
+---
+title:  Breadcrumbs
+blurb:  Breadcrumbs help prevent your users from becoming lost, especially if
+        you have deeply nested content. Get to know your options here.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Breadcrumbs by default appear on every page of your help file, except for the
+main landing page (which, as root, has no breadcrumb trail).
+
+There are two helpers that can each produce the breadcrumbs widget that’s at
+the top:
+ 
+`nav_breadcrumbs`
+ : Produces breadcrumbs ending with the title of the current page. 
+ 
+`nav_breadcrumbs_alt`
+ : Produces breadcrumbs with “Current page” at the end instead of the title of
+   the current page.
+
+
+Configuration
+-------------
+Breadcrumbs are configured in your `config.rb` file using the `Breadcrumbs`
+option, which can be set to one of the two helpers above, or to `nil` to
+disable breadcrumbs completely.
+
+If you design your own breadcrumbs helper, you can use the same configuration
+setting to use it instead, too: simply specify the name of your own breadcrumbs
+helper.
+
+
+Including Breadcrumbs
+---------------------
+_Middlemac_ includes breadcrumbs in the `layout-html4` template.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/050_navigator.html.md.erb

@@ -0,0 +1,26 @@
+---
+title:  Navigator
+blurb:  Learn how the page navigator can make navigation easy for your users, as
+        well as how to turn it on or off for groups and individual pages.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Near the bottom of this page you can see the navigator. It’s visible because
+this page’s parent `index.html` file includes `navigate: true` in its
+frontmatter.
+
+Setting `:navigate` in the frontmatter will cause all pages with an
+[order][groups] to display the navigator. This can be overridden on a
+page-per-page basis by using the `:navigator` frontmatter key, e.g., `navigator:
+false`.
+
+The helper `nav_prev_next` provides the navigator structure, and the appearance
+is set in CSS.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/060_targets.html.md.erb

@@ -0,0 +1,63 @@
+---
+title:  Targets
+blurb:  Targets let you build help files that are specific to each version or
+        variant of your Mac OS X application.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+Demonstration
+--------------
+<% if target_name?(:pro) %>
+You are reading this help book using the `:pro` target. You can try rebuilding
+the project or starting the server with the `:free` target to get a different
+result.
+<% end %>
+<% if target_name?(:free) %>
+You are reading this help book using the `:free` target. You can try rebuilding
+the project or starting the server with the `:pro` target to get a different
+result.
+<% end %>
+
+
+How did this work?
+------------------
+The source file uses a simple conditional and helper to display content based on
+the target name. Here’s the (nearly) exact code that was used:
+
+~~~ erb
+<%% if target_name?(:pro) %>
+You are reading this help book using the `:pro` target. You can try rebuilding
+the project or starting the server with the `:free` target to get a different
+result.
+<%% end %>
+<%% if target_name?(:free) %>
+You are reading this help book using the `:free` target. You can try rebuilding
+the project or starting the server with the `:pro` target to get a different
+result.
+<%% end %>
+~~~
+
+Why “nearly” exact code? If you examine the `.md.erb` file you will see how to
+escape ERB delimiters so that ERB doesn’t try to process them as Ruby code.
+In order to display `<%% %>` it is necessary to specify `<%%% %>` in code
+blocks. And of course you can read about code blocks and other Markdown
+formatting on
+[kramdown’s documentation site](http://kramdown.gettalong.org/documentation.html).
+
+
+Include or exclude entire pages
+-------------------------------
+
+Whether you’re currently using the `:pro` or `:free` target, try visiting
+each of these pages:
+
+- [sample page excludes target `:free`](not_free.html)
+- [sample page excludes target `:pro`](not_pro.html)

data/documentation_project/Contents/Resources/Base.lproj/050_structure/070_features.html.md.erb

@@ -0,0 +1,122 @@
+---
+title:  Features
+blurb:  Features work similarly to targets, but give you much more fine-grained
+        control.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+Demonstrations
+---------------
+
+* * *
+
+<% if target_feature?(:feature_advertise_pro) %>
+**New! Today Only!!! Act before this special offer is gone forever!** Why settle
+for the limitations of _Middlemac Free_ when you can upgrade to _Middlemac Pro_
+for this limited time, special price of only $1299.99?
+
+(Note: there is no _Middlemac Pro_. This is part of the Features demonstration.)
+
+* * *
+<% end %>
+
+
+<% if target_feature?(:feature_performs_miracles) %>
+If you open your water faucet, clean, safe, potable water will flow out of it.
+_Middlemac_ has made this miracle happen for you.
+
+* * *
+<% end %>
+
+
+<% if target_feature?(:feature_insults_user) %>
+If you have made it this far, dear reader, you should know that if brains were
+dynamite, you wouldn’t have enough to blow your nose.
+<% else %>
+If you have made it this far, dear reader, you should know that you are one of
+the best people in the world.
+<% end %>
+
+* * *
+
+<% if target_feature?(:feature_shows_pink_rectangle) %>
+I made a special, pink rectangle just for you!
+<svg style="width:50px; height:35px; display:block; margin:auto;">
+  <rect width="50" height="35" style="fill:pink;stroke-width:0" />
+</svg>
+<% else %>
+Too bad; other people got to see a nice, pink rectangle.
+<% end %>
+
+* * *
+
+
+Recall our targets’ `feature` settings
+--------------------------------------
+
+Our `:free` target uses these `feature` settings:
+
+~~~ ruby
+:feature_advertise_pro        => true,
+:feature_performs_miracles    => false,
+:feature_insults_user         => true,
+:feature_shows_pink_rectangle => true,
+~~~
+
+And `:pro` was setup with these `feature` settings:
+
+~~~ ruby
+:feature_advertise_pro        => false,
+:feature_performs_miracles    => true,
+:feature_insults_user         => false,
+:feature_shows_pink_rectangle => true,
+~~~
+
+Depending on the target that you are currently viewing, you should very easily
+be able to correlate what appears in the **Demonstrations** section with the
+`feature`s settings above. Try changing some of the values and see what happens
+to this page.
+
+
+Targets vs Features
+-------------------
+
+While you can use targets exclusively, it’s then up to you to decide which
+content you want to include in each of your help books when your Mac OS X
+applications have different features. For example, what happens when you decide
+to enable or disable a feature in a future release of your application? If you
+use targets alone, you’ll have to go back and make a lot of changes to your
+help content. If you use **features**, instead, it’s as simple as toggling the
+value of your target’s `:features` sub-key between `true` and `false`.
+
+
+How did this work?
+------------------
+Features work nearly identically to [targets][targets]. Instead of using the
+`target_name?` helper, use the `target_feature?` helper instead. For example:
+
+~~~ erb
+<%% if target_feature?(:feature_insults_user) %>
+If you have made it this far, dear reader, you should know that if brains were
+dynamite, you wouldn’t have enough to blow your nose.
+<%% else %>
+If you have made it this far, dear reader, you should know that you are one of
+the best people in the world.
+<%% end %>
+~~~
+
+
+Include or exclude entire pages
+-------------------------------
+
+Just as with targets, you can use front matter `target` and `exclude` to include
+or exclude entire pages.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/index.html.md.erb

@@ -0,0 +1,21 @@
+---
+title:  "Workflow: Develop your Help Structure"
+blurb:  Before you get busy writing all of your content, learn how
+        <em>Middlemac</em> expects your project to be structured, and how this
+        structure benefits you.
+layout: template-logo-large
+navigate: true
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+* * *
+
+<%= nav_legitimate_children %>
+
+* * *

data/documentation_project/Contents/Resources/Base.lproj/050_structure/not_free.html.md.erb

@@ -0,0 +1,43 @@
+---
+title:     Invisible On Free
+blurb:     This page is not available for target `:free`, as a demonstration of
+           the use of targets.
+layout:    template-logo-small
+navigator: false
+exclude:
+ - :free
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+How is this accomplished?
+-------------------------
+
+This is the frontmatter for this page. Note the key `exclude`, which indicates
+that this is page should be hidden from _Middleman_’s navigation system and
+build output.
+
+~~~ yaml
+---
+title:     Invisible On Free
+blurb:     This page is not available for target `:free`, as a demonstration of
+           the use of targets.
+layout:    template-logo-small
+navigator: false
+exclude:
+ - :free
+---
+~~~
+
+The opposite of `exclude` is `target`. If you use `target`, only those targets
+included in the target list will be included in _Middlemac_ navigation.
+Using `exclude` overrides `target`.
+
+Note that `target` and `exclude` are lists; you can specify multiple targets and
+[features][features_overview] (which also can be used).

data/documentation_project/Contents/Resources/Base.lproj/050_structure/not_pro.html.md.erb

@@ -0,0 +1,43 @@
+---
+title:     Invisible On Pro
+blurb:     This page is not available for target `:pro`, as a demonstration of
+           the use of targets.
+layout:    template-logo-small
+navigator: false
+exclude:
+ - :pro
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+How is this accomplished?
+-------------------------
+
+This is the frontmatter for this page. Note the key `exclude`, which indicates
+that this is page should be hidden from _Middleman_’s navigation system and
+build output.
+
+~~~ yaml
+---
+title:     Invisible On Pro
+blurb:     This page is not available for target `:pro`, as a demonstration of
+           the use of targets.
+layout:    template-logo-small
+navigator: false
+exclude:
+ - :pro
+---
+~~~
+
+The opposite of `exclude` is `target`. If you use `target`, only those targets
+included in the target list will be included in _Middlemac_ navigation.
+Using `exclude` overrides `target`.
+
+Note that `target` and `exclude` are lists; you can specify multiple targets and
+[features][features_overview] (which also can be used).

data/documentation_project/Contents/Resources/Base.lproj/060_content/010_frontmatter.html.md.erb

@@ -0,0 +1,88 @@
+---
+title:  Frontmatter and keys
+blurb:  Examine all of the different frontmatter keys and their use in a single
+        location.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+Frontmatter
+-----------
+Frontmatter is metadata that is included at the top of every content page but
+will not be present in the output. It is used to provide information to
+_Middleman_ and _Middlemac_ on a page by page and group basis.
+
+Here is the frontmatter from this very page’s source file:
+
+~~~ yaml
+---
+title:  Frontmatter and keys
+blurb:  Examine all of the different frontmatter keys and their use in a single
+        location.
+layout: template-logo-medium
+---
+~~~
+
+You can also specify your own frontmatter keys and values. All frontmatter is
+available for use in your pages and templates via `current_page.data`, e.g.,
+`current_page.data.title`.
+
+Also know that if you want to style content that will be rendered to HTML in
+the frontmatter, such as in a blurb, then HTML is required. HAML and Markdown
+do not touch content in the frontmatter. For example, if you want to emphasize
+text in a blurb, you will have do to something like this example:
+
+~~~ yaml
+blurb: I must <em>emphasize</em> that going to war with an empty treasury is bad.
+~~~
+
+
+Middlemac Frontmatter Keys
+--------------------------
+
+`title`
+ : The page title will be used in to the HTML `<title>` tag for every page,
+   and more importantly, will be the text displayed for links by all of
+   _Middlemac_’s built-in partials.
+
+`blurb`
+ : The blurb will be used as a description for a link for the included
+   _Middlemac_ partials that render indexes. This help documentation also
+   repeats the blurb at the top of every article.
+
+`layout`
+ : Specify the layout or template to use to render the page. If you don’t
+   specify a layout, then the `layout-html4` layout will be used by default.
+
+`xhtml`
+ : Specify this key if you want to force a page to use the `layout-xhtml`
+   layout instead of an html4 layout. You should never do this, though, except
+   for the main, top-level landing page. Apple’s help specifications require
+   HTML4.
+
+`order`
+ : Set the sorting/display order for a particular file within its group.
+
+`navigate`
+ : When used in a group’s parent (i.e., the `index.html` for the group) then
+   members of the group will display the page navigator buttons.
+
+`navigator`
+ : When set to `false`, overrides the display of the page navigator for this
+   page only.
+
+`target`
+ : Indicates which [targets][targets] and [features][features] this page is
+   applicable for.
+
+`exclude`
+ : Indicates which [targets][targets] and [features][features] this page should
+   be hidden from.