middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/090_build_application/index.html.md.erb

@@ -0,0 +1,25 @@
+---
+title:  "Workflow: Build your Mac Application"
+blurb:  Having put the final touches on your Help Book, it’s time to build your
+        Mac OS X application and see the payoff for your hard work.
+layout: template-logo-large
+navigate: true
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+While it’s true that an Apple Help Book is simply a glorified web site, there
+are details that are required to be satisfied in order to make them work with
+your Mac OS X applications. Luckily _Middlemac_ takes care of most of these
+details for you.
+
+* * *
+
+<%= nav_legitimate_children %>
+
+* * *

data/documentation_project/Contents/Resources/Base.lproj/100_reference/10_cli_ref.html.md.erb

@@ -0,0 +1,72 @@
+---
+title:  Command Line Interfaces
+blurb:  Discover the CLI’s offered by the various Ruby gems that compose
+        <em>Middlemac</em>.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+`middleman` command signature
+-----------------------------
+
+You will use `middleman` to build `middlemac` projects.
+
+~~~ bash
+bundle exec middleman [[build|server] [--target xxx]] | [build_all|all]
+~~~
+
+You can determine what the valid targets are by simply omitting a target after
+the `--target` option. This will cause an invalid target error and present you
+with a list of targets defined in the project.
+
+
+`middlemac` command signature
+-----------------------------
+
+_Middlemac_ offers its own commands for generating new projects and getting
+help.
+
+~~~ bash
+middlemac [init|documentation|help|--version]
+~~~
+
+Use `init` to generate the structure for a new, empty project, and use
+`documentation` to generate a project that can build this very documentation.
+
+
+`middlemac-extras` command signature
+------------------------------------
+
+~~~ bash
+middlemac-extras [documentation|help|--version]
+~~~
+
+Use `documentation` to generate a project that can build complete documentation.
+
+
+`middleman-pagegroups` command signature
+----------------------------------------
+
+~~~ bash
+middleman-pagegroups [documentation|partials|help|--version]
+~~~
+
+Use `documentation` to generate a project that can build complete documentation,
+or use `partials` to generate the partial files that you can use instead of
+helpers.
+
+
+`middlemac-targets` command signature
+-------------------------------------
+
+~~~ bash
+middlemac-targets [documentation|help|--version]
+~~~
+
+Use `documentation` to generate a project that can build complete documentation.

data/documentation_project/Contents/Resources/Base.lproj/100_reference/20_config_ref.html.md.erb

@@ -0,0 +1,56 @@
+---
+title:  <code>config.rb</code> Settings
+blurb:  Learn about all of the possible configuration settings for your
+        projects.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+## Targets Configuration
+
+The targets configuration appears immediately after the
+`activate :MiddlemanTargets` line.
+
+Note that `:build_dir` is included for the sake of completeness in the list
+below, but it’s not currently used in a _Middleman_ project’s `config.rb` file.
+
+<%= partial 'yard_targets_config' %>
+
+Additional information about the contents of the `targets` hash is available 
+in the [Set up your Help Project][setup-index] article.
+
+
+* * *
+
+## Page Groups Configuration
+
+The items in the block `activate :MiddlemanPageGroups do |config|` pertain to
+the automatic navigation features.
+
+<%= partial 'yard_pagegroups_config' %>
+
+
+* * *
+
+## Extras Configuration
+
+Items in the `activate :MiddlemacExtras do |config|` block control some of
+_Middlemac_’s behavior and abilities:
+
+<%= partial 'yard_extras_config' %>
+
+
+* * *
+
+## Middlemac Configuration
+
+Finally, the `activate :Middlemac do |options|` block adds some finishing
+touches.
+
+<%= partial 'yard_middlemac_config' %>

data/documentation_project/Contents/Resources/Base.lproj/100_reference/30_helpers_ext_ref.html.md.erb

@@ -0,0 +1,51 @@
+---
+title:  Extended Helpers
+blurb:  Find out how <em>Middlemac</em> changes the behavior and functions of
+        the built-in helpers.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Although _Middlemac_ has plenty of its own helpers, it also offers extensions
+to several of the built-in helpers. These appear in their own section here.
+They are organized by the Ruby gem that introduces their functionality.
+
+* * *
+
+## `middleman-targets` extended helpers
+
+<%= partial 'yard_targets_helpers_extended' %>
+
+
+* * *
+
+## `middleman-pagegroups` extended helpers
+
+<%= partial 'yard_pagegroups_helpers_extended' %>
+
+
+* * *
+
+## `middlemac-extras` extended helpers
+
+<%= partial 'yard_extras_helpers_extended' %>
+
+
+* * *
+
+## `middlemac` extended helpers
+
+<%= partial 'yard_middlemac_helpers_extended' %>
+
+* * *
+
+Note that partials listed with multiple Gems have cumulative effects. For
+example the `image_tag` partial, when used with _Middlemac_ projects, can use
+all of the parameters added by any Ruby gem.
+{:.note}

data/documentation_project/Contents/Resources/Base.lproj/100_reference/40_helpers_ref.html.md.erb

@@ -0,0 +1,45 @@
+---
+title:  Helpers
+blurb:  <em>Middlemac</em> offers several helper methods to make designing and
+        building your content easier.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+## `middleman-targets` helpers
+
+<%= partial 'yard_targets_helpers' %>
+
+
+* * *
+
+## `middleman-pagegroups` helpers (partials and helpers CSS)
+
+<%= partial 'yard_pagegroups_helpers_css' %>
+
+
+* * *
+
+## `middleman-pagegroups` helpers
+
+<%= partial 'yard_pagegroups_helpers' %>
+
+
+* * *
+
+## `middlemac-extras` helpers
+
+<%= partial 'yard_extras_helpers' %>
+
+
+* * *
+
+## `middlemac` helpers
+
+<%= partial 'yard_middlemac_helpers' %>

data/documentation_project/Contents/Resources/Base.lproj/100_reference/50_resource_ext_ref.html.md.erb

@@ -0,0 +1,25 @@
+---
+title:  Resource Extensions
+blurb:  Find out what new resource methods are available to your project’s
+        pages.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+## `middleman-targets` resource extensions
+
+<%= partial 'yard_targets_resources' %>
+
+
+* * *
+
+## `middleman-pagegroups` resource extensions
+
+<%= partial 'yard_pagegroups_resources' %>
+

data/documentation_project/Contents/Resources/Base.lproj/100_reference/index.html.md.erb

@@ -0,0 +1,26 @@
+---
+title:  Reference
+blurb:  The content in this section is pure reference without the blather. If
+        you know what you’re doing and just need to check something, it’s
+        probably right here.
+layout: template-logo-large
+navigate: true
+---
+
+<%= md_images %>
+<%= md_links %>
+
+<%= current_page.data.title %>
+==============================
+<%= current_page.data.blurb %>
+
+_Middlemac_ is a system consisting of four Ruby gems plus _Middleman_ and all of
+its gems. As such all of the wonderful things that make _Middlemac_ such a nice
+tool in the composite come from several sources. This reference section attempts
+to put everything together in a single spot.
+
+* * *
+
+<%= nav_legitimate_children %>
+
+* * *

data/documentation_project/Contents/Resources/Base.lproj/110_acknowledgements/index.html.md.erb

@@ -0,0 +1,61 @@
+---
+title:  Acknowledgements and License
+blurb:  Discover many of the people whom <em>Middlemac</em> owes thanks to, and
+        read about <em>Middlemac</em>’s open source license. 
+layout: template-logo-small
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+Acknowledgements
+----------------
+_Middlemac_ depends entirely on [_Middleman_](http://middlemanapp.com), without
+which this work would not be practical.
+
+We have chosen the name _Middlemac_ in homage to _Middleman_ and this choice
+should not be inferred to mean that this project is related to _Middleman_.
+
+We have designed a logo very similar to that of the _Middleman_ project. It
+should not be inferred that _Middlemac_ is related to the _Middleman_ project
+based on this design choice. We will happily change the logo if anyone from the
+official _Middleman_ project makes such a request.
+
+_Middleman_ itself depends on a whole ecosystem of free and open source
+software. Please [visit http://middlemanapp.com](http://middlemanapp.com) in
+order to have a full understanding of all of the pieces that make _Middlemac_
+work. Without all of these contributions, _Middleman_ and _Middlemac_ would not
+be possible.
+
+
+License
+-------
+
+_Middlemac_ itself is released under the permissive MIT License, printed below.
+_Middlemac_ depends on other components in order to work. Those components are
+_not_ distributed with _Middlemac_ and have their own licences which the authors
+of _Middlemac_ do not pretend to override.
+
+### The MIT License (MIT)
+
+Copyright (c) 2014-2016 Jim Derry and balthisar.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/documentation_project/Contents/Resources/Base.lproj/120_backwards_compatibility/index.html.md.erb

@@ -0,0 +1,88 @@
+---
+title:  Backwards Compatibility
+blurb:  Notes about Backwards Compatibility with earlier versions of Middlemac.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+_Middlemac_ version 2.0.0 is a **major** update. It’s an API-breaking update and
+projects using _Middlemac_ version 1.0 will _not_ build without some changes to
+your project.
+
+Additionally because _Middlemac_ now requires _Middleman_ 4.1.7 or higher, there
+are some _Middleman_-related changes, too.
+
+This version of _Middlemac_ is a complete rewrite, and it was designed in such a
+way that in the future it _can_ be upgraded without breaking your projects. We
+hope that the improvements, though, make it completely worth the trouble to
+update.
+
+
+Upgrading a project
+-------------------
+
+No automated method of upgrading a project is provided, but the steps for
+achieving an upgrade are fairly simple.
+
+### Files
+
+`middlemac.rb`
+  : This file is no longer required and should be removed from your project.
+    _Middlemac_ is now a proper Ruby gem and is managed by Ruby directly.
+
+`Gemfile`
+  : You must replace your `Gemfile` with ours, or at least ensure that your
+    `Gemfile` is edited to reflect the new gem requirements.
+
+`config.rb`
+  : You should use our new `config.rb` as a starting point for replacing your
+    current `config.rb` file. Most of the changes are obvious, and pay special
+    attention to some of the items that have letter case changes.
+    
+`Contents/Resources/Base.lproj/assets/`
+`   layouts/layout-html4.haml`
+`   fonts/*`
+`   stylesheets/*`
+  : These files from a new project (or this sample documentation project) must
+    replace the corresponding files in your current project. In particular the
+    `layouts/layout-html4.haml` file enables the new `breadcrumbs` configuration
+    option. The new `fonts/` directory ensures that the required `font-awesome`
+    fonts are always available, and there have been visual tweaks in all of the
+    `stylesheets/` files (in particular we now have to include the `github`
+    styles in a new way).
+
+
+### Configuration Changes
+
+Amongst the changes mentioned above to `config.rb` is the removal of support for
+_Middleman_’s `partials_dir` configuration setting. However in order to maintain
+backwards compatibility we have preserved this functionality in _Middlemac_.
+Simply move the `partials_dir` setting into the `activate Middlemac` block.
+
+If you are following _Middlemac_ conventions, you can delete the `partials_dir`
+setting completely, as the default is appropriate.
+{: .note }
+
+
+### Other Partials Changes
+
+By default the automatic navigation partials are no longer included in the
+sample project, and if you were using them you will have to keep your own
+partials.
+  
+New partials are available as part of the required `middleman-pagegroups` gem,
+but we also suggest that you consider using the new helpers instead of partials.
+
+Also keep in mind that `md_links` and `md_images` helpers replace previous
+partial functionality. Use these helpers to generate Markdown shortcuts instead.
+
+
+### Other Changes
+
+_Read_ this documentation and have a close look at the sample project. This is
+a big **2.0** release, and lots of things have changed for the better. Before
+long, you’ll have your old projects working again.