middleman-targets 1.0.0

data/documentation_project/source/frontmatter.html.md.erb

@@ -0,0 +1,70 @@
+---
+title:  Front Matter
+layout: template-logo-medium
+---
+
+# Front Matter
+
+By default every page in a Middleman project is included in the build output,
+but `middleman-targets` provides means to ensure that only target- and
+feature-specific pages are included. This is controlled by data in your pages’
+front matter.
+
+## `target`
+
+The `target` key acts to ensure that _only_ targets and features in its array
+are included in the build. For example:
+
+~~~ erb
+---
+target:
+ - :free
+ - :insults_user
+---
+~~~
+
+This example page would only be built if the target **or** feature is `free`
+or `insults_user`.
+
+Note there is no distinction between targets and features in this list. If the
+target is `insults_user` or the feature is `free`, then output will be enabled.
+{:.note}
+
+
+## `exclude`
+
+The `exclude` key ensures that pages are only built for targets and features
+that do not appear in the `exclude` array. For example:
+
+~~~ erb
+---
+exclude:
+ - :pro
+ - :insults_user
+---
+~~~
+
+This example would build the page, unless the current target or feature were
+`pro` **or** `insults_user`, i.e., either condition prevents the page from
+ being output.
+
+Note there is no distinction between targets and features in this list. If the
+target is `insults_user` or the feature is `free`, then output will be enabled.
+{:.note}
+
+
+## Precedence
+
+`exclude` will always override `target`.
+
+
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="index.html">Welcome to middleman-targets</a></li>
+<li><a href="simple-demo.html">Simple features demonstration</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="helpers-resources.html">Helpers and Resources</a></li>
+</ul>
+<% end %>

data/documentation_project/source/helpers-resources.html.md.erb

@@ -0,0 +1,98 @@
+---
+title:  Helpers and Resources
+layout: template-logo-medium
+---
+
+# Helpers and Resources
+
+`middleman-targets` includes some helpers and some page resources that make
+working with multiple targets easier.
+
+
+## Resources
+
+Middleman’s resource list is available to all of your templates and pages, and
+also available for your own helpers, and `middleman-targets` provides a couple
+of resource map additions than can prove useful when developing your own
+helpers.
+
+`valid_features`
+
+ : `valid_features` returns an array of features that are enabled and applicable
+   to the current build target. Although available for output in your pages,
+   this is probably most useful for developing your own helpers.
+   
+   By way of example, the raw output of `<%%= current_page.valid_features %>`
+   on this page is `<%= current_page.valid_features %>`. The output will be
+   different if you switch targets.
+   
+`targeted?`
+
+ : Determines if the resource is eligible for inclusion in the current page
+   based on the front matter `target` and `exclude` data fields
+  
+   - if `frontmatter:target` is used, the target or feature appears in the 
+     front matter, and
+   - if `frontmatter:exclude` is used, the target or enabled feature does NOT
+     appear in the frontmatter.
+     
+   In general you won't use this resource method on pages because resources will
+   already be excluded before you have a chance to check them, and so any
+   leftover resources will always return true for this method. This method could
+   be valuable in writing your own helpers, however.
+
+
+## Helpers
+
+`target_name`
+
+  : Return the current build target.
+
+`target_name?(proposal)`
+
+ : Is the current target `proposal`?
+
+`target_feature?(feature)`
+
+ : Does the target have the feature `feature`?
+
+`target_value(key)`
+
+ : Attempts to return the value for they key `key` for the current target.
+ 
+`image_tag`
+
+ : Extends Middleman’s built-in `image_tag` helper in order to support:
+ 
+   - automatic target-specific images. Note that this only works on local files.
+   - target and feature dependent images.
+   - absolute paths
+   
+   Automatic target-specific images are described in 
+   [Simple features demonstration](simple-demo.html), and allow you to specify
+   an image with a magic prefix in your source code which will be substituted
+   with a target-specific image for output.
+   
+   Target- and feature-dependent images add the `:target` and `:feature`
+   options to the `image_tag` parameter array, indicating that the image should
+   only be used in the condition specified. For example,
+   `image_tag 'my_image.png', :feature => 'insults_user'` will only include the
+   image if the current target has the feature `insults_user` enabled.
+   
+   As a freebie that’s not specifically related to multiple targets, our
+   `image_tag` helper also works with absolute image paths, where ”absolute”
+   means relative to your project directory. Specifying `/assets/images/photo.png`
+   will correctly reference that image as if your project directory were the
+   root filesystem.
+
+
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="index.html">Welcome to middleman-targets</a></li>
+<li><a href="simple-demo.html">Simple features demonstration</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="frontmatter.html">Front Matter</a></li>
+</ul>
+<% end %>

data/documentation_project/source/index.html.md.erb

@@ -0,0 +1,59 @@
+---
+title:  Welcome to middleman-targets
+layout: template-logo-large
+---
+
+<div markdown="1">
+
+# Welcome to middleman-targets
+
+The `middleman-targets` gem is an extension to [Middleman][1] that gives you the
+ability to specify multiple build targets and provides useful tools for dealing
+with multiple targets and features.
+
+- Generate multiple targets for different uses using the same basic project
+  structure, content, and code.
+- Assign “features” to targets which give you fine-grained control over what
+  content appears in each target.
+- Select images automatically based on the current build target.
+- Use images selectively based on the current build target or feature.
+- Include target-specific versions of data in a consistent fashion.
+
+`middleman-targets` was written as part of the [Middlemac][2] Help Book building
+system for Mac OS X applications, but it’s suitable for any project that
+requires multiple build targets, such as software documentation, training
+manuals, and more.
+
+This documentation will refer to two sample targets: `:pro` and `:free`, which
+is something that a typical software publisher might do.
+
+Note that parts of this documentation will have different content depending on
+whether you are building the `:pro` or `:free` target. These are just examples,
+though, and all of the technical documentation is the same.
+{:.note}
+
+* * *
+
+- [Simple features demonstration](simple-demo.html)
+- [Build and Serve different targets](build-serve-targets.html)
+- [Configuration](target-feature-config.html)
+- [Helpers and Resources](helpers-resources.html)
+- [Front Matter](frontmatter.html)
+
+
+</div>
+
+ [1]: https://middlemanapp.com/
+ [2]: https://github.com/middlemac
+
+
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="simple-demo.html">Simple features demonstration</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="helpers-resources.html">Helpers and Resources</a></li>
+<li><a href="frontmatter.html">Front Matter</a></li>
+</ul>
+<% end %>

data/documentation_project/source/javascripts/all.js

@@ -0,0 +1 @@
+// This is where it all goes :)

data/documentation_project/source/layouts/layout.haml

@@ -0,0 +1,9 @@
+!!! 5
+%html
+  %head
+    %title= current_page.data.title || 'middleman-targets'
+    %meta{:content => 'text/html; charset=utf-8', :'http-equiv' => 'Content-Type'}/
+    = stylesheet_link_tag 'style'
+    = javascript_include_tag  'all'
+  %body
+    = yield

data/documentation_project/source/layouts/template-logo-large.haml

@@ -0,0 +1,17 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-large
+    %div
+      %div
+        = image_tag 'all-logo-small.png', :alt => 'middleman-targets logo'
+        %h1= "#{product_name}"
+        %h2= "version #{product_version}"
+        %a{:href => product_uri}= product_uri
+
+      - if content_for?(:seeAlso)
+        .related_topics
+          %h1 See Also
+          = yield_content :seeAlso
+
+    %div
+      .yield-content
+        ~ yield

data/documentation_project/source/layouts/template-logo-medium.haml

@@ -0,0 +1,14 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-medium
+    %div
+      .yield-content
+        ~ yield
+
+    %div
+      %div
+        = image_tag 'all-logo-small.png', :alt => 'middleman-targets logo'
+      .related_topics
+
+        - if content_for?(:seeAlso)
+          %h1 See Also
+          = yield_content :seeAlso

data/documentation_project/source/layouts/template-logo-small.haml

@@ -0,0 +1,11 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-small
+    .yield-content
+      = image_tag 'all-logo-small.png', :alt => 'middleman-targets logo'
+      ~ yield
+
+    .related_topics
+      - if content_for?(:seeAlso)
+        %hr
+        %h1 See Also
+        = yield_content :seeAlso

data/documentation_project/source/only-free.html.md.erb

@@ -0,0 +1,38 @@
+---
+title:  Only for :free
+layout: template-logo-small
+target:
+ - :free
+---
+
+# Only for :free
+
+This page is only available to the `:free` target, and no other target will make
+this page available during build or while running the server.
+
+This is accomplished by using the `target` key in the
+[front matter](frontmatter.html) data, and specifying only the `:free` target.
+
+~~~ erb
+---
+title:  Only for :free
+layout: template-logo-small
+target:
+ - :free
+---
+~~~
+
+Note that `target` is a YAML array; you can include multiple `target` targets
+and/or features here.
+{:.note}
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="index.html">Welcome to middleman-targets</a></li>
+<li><a href="simple-demo.html">Simple features demonstration</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="helpers-resources.html">Helpers and Resources</a></li>
+<li><a href="frontmatter.html">Front Matter</a></li>
+</ul>
+<% end %>

data/documentation_project/source/only-pro.html.md.erb

@@ -0,0 +1,39 @@
+---
+title:  Only for :pro
+layout: template-logo-small
+exclude:
+ - :free
+---
+
+# Only for :pro
+
+This page is only available to targets that are not `:free`; in this sample
+project, that means that only the `:pro` target will make this page available
+during build or while running the server.
+
+This is accomplished by using the `exclude` key in the
+[front matter](frontmatter.html) data, and excluding the `:free` target.
+
+~~~ erb
+---
+title:  Only for :pro
+layout: template-logo-small
+exclude:
+ - :free
+---
+~~~
+
+Note that `exclude` is a YAML array; you can include multiple `exclude` targets
+and/or features here.
+{:.note}
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="index.html">Welcome to middleman-targets</a></li>
+<li><a href="simple-demo.html">Simple features demonstration</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="helpers-resources.html">Helpers and Resources</a></li>
+<li><a href="frontmatter.html">Front Matter</a></li>
+</ul>
+<% end %>

data/documentation_project/source/simple-demo.html.md.erb

@@ -0,0 +1,183 @@
+---
+title:  Simple features demonstration
+layout: template-logo-medium
+---
+
+# Simple features demonstration
+
+This page demonstrates most of the features provided by `middleman-targets`.
+Notably on this page (as on all others) you can see that the logo reflects
+the current target. If you build or serve `:pro` you will see the logo text
+differently than building or serving `:free`.
+
+This is accomplished by using the enhanced `image_tag` 
+[helper](helpers-resources.html) and specifying an image with a magic prefix (in
+this project the prefix is `all-`).
+
+
+## Current target
+
+Your current `target_name` is `<%= target_name %>`, and this `<%= target_name %>`
+output is a result of the `target_name` [helper](helpers-resources.html).
+
+This in itself isn’t so useful; your users probably don’t care about the
+internal names for your targets. However…
+
+
+## Target based conditions
+
+You can vary the output per target using simple conditional expressions in
+whatever template language you use. Since the source for this page is an ERB
+file, let’s show an example using ERB:
+
+<% if target_name?(:pro) %>
+**You are viewing the `pro` target.**
+<% else %>
+**You are viewing the `free` target.**
+<% end %>
+{:.note}
+
+This output is a result of this conditional in the source file:
+
+~~~ erb
+<%% if target_name?(:pro) %>
+**You are viewing the `pro` target.**
+<%% else %>
+**You are viewing the `free` target.**
+<%% end %>
+~~~
+
+If you only have a few targets without a large variety of feature differences,
+then using target based conditions may be ideal for you. However as things tend
+to become more complex, micromanaging which content belongs to which feature
+tends to become unmanageable.
+
+
+## Feature based conditions
+
+Applying content based on feature gives you much greater flexibility and control
+over what content is included in your builds. The concept is simple: add an
+identical list of features to each target in your [`config.rb`](target-feature-config.html)
+file, and then either enable them (`true`) or disable them (`false`) for each
+target.
+
+For example, the `config.rb` for this project includes the feature
+`feature_advertise_pro`, which is something that might be reasonable to include
+in your free project but unnecessary in your professional project, e.g.:
+
+<% if target_feature?(:feature_advertise_pro) %>
+Did you know that the Professional version of project has an even better message
+for you?
+<% else %>
+As a thank you to our valued, paying customers we offer you, well, thanks!
+<% end %>
+{:.note}
+
+The notice above was produced with this simple code:
+
+~~~ erb
+<%% if target_feature?(:feature_advertise_pro) %>
+As a thank you to our valued, paying customers we offer you, well, thanks!
+<%% else %>
+Did you know that the Professional version of project has an even better message
+for you?
+<%% end %>
+~~~
+
+Managing your content with features instead of targets can make it dead simple
+to change your documentation in the event that your product features change.
+
+
+## Target specific data
+
+This project’s [`config.rb`](target-feature-config.html) defines a sample data
+key called `sample_key` containing a different message for each target.
+
+<%= @app.config[:targets][@app.config[:target]][:sample_key] %>
+{:.note}
+
+That output was generated with this code:
+
+~~~ erb
+<%%= @app.config[:targets][@app.config[:target]][:sample_key] %>
+~~~
+
+However that’s a bit fussy, and could be output much more easily by using a
+built-in [helper](helpers-resources.html):
+
+<%= target_value(:sample_key) %>
+{:.note}
+
+~~~ erb
+<%%= target_value(:sample_key) %>
+~~~
+
+
+## Omitting pages
+
+Using [frontmatter data](frontmatter.html) you can selectively include and/or
+exclude entire pages from your project based on target and/or features. The
+two links (but not destinations) that follow are present in both the `:pro`
+and `:free` targets, but depending on which target you are viewing the
+destination will not be present.
+
+- [Link to a `:free`-only page](only-free.html)
+- [Link to a `:pro`-only page](only-pro.html)
+
+Code revealing how this is done is present on those two pages.
+
+
+## Target and feature specific images
+
+Our `image_tag` helper adds the `:target` and `:feature` parameters to the
+built-in helper which is intended as a space-saver compared to 
+`<%% if target_name?(…) %>` and `<%% if target_feature?(…) %>` conditional
+blocks. Simply supply the desired target or feature in the options parameter
+and the image will be included or excluded appropriately.
+
+<%= image_tag 'pro-logo-small.png', :target => 'pro' %>
+<%= image_tag 'free-logo-small.png', :target => 'free' %>
+
+You will see an appropriate version of the logo based on this code:
+
+~~~ erb
+<%%= image_tag 'pro-logo-small.png', :target => 'pro' %>
+<%%= image_tag 'free-logo-small.png', :target => 'free' %>
+~~~
+
+However in the case of target based image selection, there’s an even easier
+way…
+
+
+## Automatic target based images
+
+By specifying a magic prefix defined in your [`config.rb`](target-feature-config.html)
+file, you can enable automatic substitution of images based on the current
+build target. For example:
+
+<%= image_tag 'all-logo-small.png' %>
+
+The above, target-appropriate image was produced with this single line of code:
+
+~~~ erb
+<%%= image_tag 'all-logo-small.png' %>
+~~~
+
+If you look at the `images/` directory in this project’s source, you’ll notice
+that there’s not even a file named `all-logo-small.png`.
+
+Do note, however, that this automatic substitution _only_ works for images that
+are located within your project’s directory, and not from assets not available
+in the file system.
+{:.note}
+
+
+<% content_for :seeAlso do %>
+<ul>
+<li><a href="index.html">Welcome to middleman-targets</a></li>
+<li><a href="build-serve-targets.html">Build and Serve different targets</a></li>
+<li><a href="target-feature-config.html">Configuration</a></li>
+<li><a href="helpers-resources.html">Helpers and Resources</a></li>
+<li><a href="frontmatter.html">Front Matter</a></li>
+</ul>
+<% end %>