middlemac-extras 1.0.0

data/documentation_project/source/books/science fiction/about.html.md.erb

@@ -0,0 +1,29 @@
+---
+title:    archives/about
+blurb:    Describes your legal rights and obligations for using these materials.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+**Copyright (c) 2016 Jim Derry**
+
+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/source/books/science fiction/index.html.md.erb

@@ -0,0 +1,35 @@
+---
+title:    SCIENCE FICTION INDEX
+blurb:    <em>middlemac-extras</em> adds several developer conveniences..
+layout:   template-logo-large
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+Although developed for **MiddleMac**, the `middlemac-extras` extension for
+Middleman is a great way to add handy developer conveniences to your Middleman
+project.
+
+Features such as CSS-based image sizes, automatic Markdown reference-style
+links, and an automatic @2x `image_size` helper will increase your productivity.
+
+* * *
+
+# Link to license
+
+See the [license][license].
+
+Go to the [index][index].
+
+Go to the [science fiction][science_fiction_index] index.
+
+Go to the [science fiction](books/science fiction/index.html) index.
+
+* * *
+
+<%= md_links %>
+
+~~~ markdown
+<%= md_links %>
+~~~

data/documentation_project/source/books/science fiction/past_science_fiction/about.html.md.erb

@@ -0,0 +1,29 @@
+---
+title:    archives/about
+blurb:    Describes your legal rights and obligations for using these materials.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+**Copyright (c) 2016 Jim Derry**
+
+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/source/books/science fiction/past_science_fiction/index.html.md.erb

@@ -0,0 +1,35 @@
+---
+title:    SCIENCE FICTION INDEX
+blurb:    <em>middlemac-extras</em> adds several developer conveniences..
+layout:   template-logo-large
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+Although developed for **MiddleMac**, the `middlemac-extras` extension for
+Middleman is a great way to add handy developer conveniences to your Middleman
+project.
+
+Features such as CSS-based image sizes, automatic Markdown reference-style
+links, and an automatic @2x `image_size` helper will increase your productivity.
+
+* * *
+
+# Link to license
+
+See the [license][license].
+
+Go to the [index][index].
+
+Go to the [science fiction][science_fiction_index] index.
+
+Go to the [science fiction](books/science fiction/index.html) index.
+
+* * *
+
+<%= md_links %>
+
+~~~ markdown
+<%= md_links %>
+~~~

data/documentation_project/source/books/science fiction/past_science_fiction/past_far/about.html.md.erb

@@ -0,0 +1,29 @@
+---
+title:    archives/about
+blurb:    Describes your legal rights and obligations for using these materials.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+**Copyright (c) 2016 Jim Derry**
+
+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/source/books/science fiction/past_science_fiction/past_far/index.html.md.erb

@@ -0,0 +1,35 @@
+---
+title:    SCIENCE FICTION INDEX
+blurb:    <em>middlemac-extras</em> adds several developer conveniences..
+layout:   template-logo-large
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+Although developed for **MiddleMac**, the `middlemac-extras` extension for
+Middleman is a great way to add handy developer conveniences to your Middleman
+project.
+
+Features such as CSS-based image sizes, automatic Markdown reference-style
+links, and an automatic @2x `image_size` helper will increase your productivity.
+
+* * *
+
+# Link to license
+
+See the [license][license].
+
+Go to the [index][index].
+
+Go to the [science fiction][science_fiction_index] index.
+
+Go to the [science fiction](books/science fiction/index.html) index.
+
+* * *
+
+<%= md_links %>
+
+~~~ markdown
+<%= md_links %>
+~~~

data/documentation_project/source/books/science fiction/past_science_fiction/past_near/about.html.md.erb

@@ -0,0 +1,29 @@
+---
+title:    archives/about
+blurb:    Describes your legal rights and obligations for using these materials.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+**Copyright (c) 2016 Jim Derry**
+
+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/source/books/science fiction/past_science_fiction/past_near/index.html.md.erb

@@ -0,0 +1,35 @@
+---
+title:    SCIENCE FICTION INDEX
+blurb:    <em>middlemac-extras</em> adds several developer conveniences..
+layout:   template-logo-large
+navigate: false
+---
+
+# <%= current_page.data.title %>
+
+Although developed for **MiddleMac**, the `middlemac-extras` extension for
+Middleman is a great way to add handy developer conveniences to your Middleman
+project.
+
+Features such as CSS-based image sizes, automatic Markdown reference-style
+links, and an automatic @2x `image_size` helper will increase your productivity.
+
+* * *
+
+# Link to license
+
+See the [license][license].
+
+Go to the [index][index].
+
+Go to the [science fiction][science_fiction_index] index.
+
+Go to the [science fiction](books/science fiction/index.html) index.
+
+* * *
+
+<%= md_links %>
+
+~~~ markdown
+<%= md_links %>
+~~~

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

@@ -0,0 +1,72 @@
+---
+title:    Setting up config.rb
+blurb:    Review the key configuration values for making this extension work.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+<%= md_links %>
+<% content_for :seeAlso do %>
+<ul>
+  <li><a href="/">Welcome to <code>middlemac-extras</code></a></li>
+  <li><a href="css_image_sizes.html">The <code>css_image_sizes</code> helper</a></li>
+  <li><a href="image_tag.html">The <code>image_tag</code> helper</a></li>
+  <li><a href="md_images.html">The <code>md_images</code> helper</a></li>
+  <li><a href="md_links.html">The <code>md_links</code> helper</a></li>
+  <li><a href="license.html">The MIT License</a></li>
+</ul>
+<% end %>
+
+# <%= current_page.data.title %>
+<%= current_page.data.blurb %>
+
+Some minimal configuration in your `config.rb` project file is required in order
+for `middlemac-extras` to be useful.
+
+## Conflicting resources
+
+This extension uses Middleman's resource map to generate a lot of the
+information that it provides. Be sure to activate other extensions that
+might manipulate the resource map before activating middlemac-extras,
+such as MiddlemanPageGroups (which changes the output names of some files).
+
+Also our `image_tag` helper should inherit from other `image_tag` helpers,
+so it's best to make sure they're activated first.
+
+
+## Extension Setup
+
+This extension has to be activated before it can be used. If you’re happy with
+the default configuration values, activation can be as simple as:
+
+~~~ ruby
+activate: MiddlemacExtras
+~~~
+
+Otherwise the block format should be used to set the extension’s configuration
+variables:
+
+~~~ ruby
+activate :MiddlemacExtras do |config|
+
+  # If set to true, then the enhanced image_tag helper will be used
+  # to include @2x srcset automatically, if the image asset exists.
+  config.retina_srcset = true
+
+  # If set to true then the `image_tag` helper will work for images even
+  # if you don't specify an extension, but only if a file exists on disk
+  # that has one of the extensions in :img_auto_extensions_order.
+  config.img_auto_extensions = true
+
+  # Set this to an array of extensions in the order of precedence for
+  # using `image_tag` without file extensions.
+  config.img_auto_extensions_order = %w(.svg .png .jpg .jpeg .gif .tiff .tif)
+
+end
+~~~
+
+
+### Extension Options
+
+The extension options are described in the code snippet, above.

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

@@ -0,0 +1,65 @@
+---
+title:    The <code>css_image_sizes</code> helper
+blurb:    Use the <code>css_image_sizes</code> helper to specify maximum sizes
+          for all of your project’s images without using unsemantic width and 
+          height attributes in your HTML code.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+<%= md_links %>
+<% content_for :seeAlso do %>
+<ul>
+  <li><a href="/">Welcome to <code>middlemac-extras</code></a></li>
+  <li><a href="image_tag.html">The <code>image_tag</code> helper</a></li>
+  <li><a href="md_images.html">The <code>md_images</code> helper</a></li>
+  <li><a href="md_links.html">The <code>md_links</code> helper</a></li>
+  <li><a href="config_rb.html">Setting up <code>config.rb</code></a></li>
+  <li><a href="license.html">The MIT License</a></li>
+</ul>
+<% end %>
+
+# <%= current_page.data.title %>
+<%= current_page.data.blurb %>
+
+It works by specifying a `max-width` and `max-height` for each image used in
+your Middleman project (except for SVG files, which don’t have dimensions).
+
+## Example
+
+When called like this:
+
+~~~ erb
+<%%= css_image_sizes %>
+~~~
+
+…the result is this:
+
+~~~ scss
+<%= css_image_sizes %>
+~~~
+
+## Use
+
+You could use this in an HTML `<style>` element on each of your pages, or better
+yet in your layouts. This has the unfortunate effect of including it in every
+one of your pages, however, and so this sample project uses like this:
+
+Contents of `stylesheets/css_image_sizes.css.erb`:
+
+~~~ erb
+<%%= css_image_sizes %>
+~~~
+
+This will create `stylesheets/css_image_sizes.css` in your build output, and
+this file is included in the project layout file:
+
+~~~ haml
+= stylesheet_link_tag 'css_image_sizes'
+~~~
+
+You will be tempted to add this helper to your `style.css.scss` file, maybe
+even renaming it to `style.css.scss.erb`, but this will not work due to the
+order that Middleman and SASS build output.
+{:.note}

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

@@ -0,0 +1,83 @@
+---
+title:    The <code>image_tag</code> helper
+blurb:    Find out how to use the enhanced <code>image_tag</code> helper so that
+          it can be even more helpful.
+layout:   template-logo-medium
+order:    40
+navigate: false
+---
+
+<%= md_links %>
+<% content_for :seeAlso do %>
+<ul>
+  <li><a href="/">Welcome to <code>middlemac-extras</code></a></li>
+  <li><a href="css_image_sizes.html">The <code>css_image_sizes</code> helper</a></li>
+  <li><a href="md_images.html">The <code>md_images</code> helper</a></li>
+  <li><a href="md_links.html">The <code>md_links</code> helper</a></li>
+  <li><a href="config_rb.html">Setting up <code>config.rb</code></a></li>
+  <li><a href="license.html">The MIT License</a></li>
+</ul>
+<% end %>
+
+# <%= current_page.data.title %>
+<%= current_page.data.blurb %>
+
+The `image_tag` helper (which also handles Markdown links) has been given some
+new capabilities aimed towards making you more productive.
+
+## Automatic image extensions
+
+When enabled this new feature allows you to omit the image extension when
+specifying an image.
+
+~~~ erb
+<%= image_tag 'image' %>
+~~~
+
+~~~ markdown
+![MyImage](image)
+~~~
+
+When enabled, the helper will look for images in your project that have an 
+extension specified by `img_auto_extensions_order` in your
+[`config.rb`][config_rb] file.
+
+### Enable this behavior
+
+You can enable or disable this behavior globally in [`config.rb`][config_rb]
+file, within the `activate :MiddlemacExtras` activation block by setting the
+value of `img_auto_extensions` to `true` or `false`.
+
+You can always enable or disable this behavior selectively by passing this
+same key with a `true` or `false` value in the helper’s parameters hash, too.
+
+
+## Automatic `srcset` for @2x images
+
+When enabled, the helper will look for @2x versions of your images within your
+project and add a a `srcset` attribute to the image tag automatically. If you
+specify your own `srcset` attribute, then this automatic behavior will never
+occur.
+
+~~~ html
+<img srcset="image@2x.png" src="image.png">
+~~~
+
+### Enable this behavior
+
+You can enable or disable this behavior globally in [`config.rb`][config_rb]
+file, within the `activate :MiddlemacExtras` activation block by setting the
+value of `retina_srcset` to `true` or `false`.
+
+You can always enable or disable this behavior selectively by passing this
+same key with a `true` or `false` value in the helper’s parameters hash, too.
+
+
+## Enables automatic_alt_tags support for absolute paths
+
+Middleman has an extension called `automatic_alt_tags` that specifies an
+automatic value for an image’s `alt` attribute if you fail to provide one.
+Unfortunately this does not work if you specify an absolute path to an image.
+
+If your project activates `automatic_alt_tags`, then `middlemac-extras` will
+apply an automatic `alt` attribute in these cases.

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

@@ -0,0 +1,53 @@
+---
+title:    Welcome to <code>middlemac-extras</code>
+blurb:    <em>middlemac-extras</em> adds several developer conveniences.
+layout:   template-logo-large
+navigate: false
+---
+
+<%= md_links %>
+
+# <%= current_page.data.title %>
+
+Although developed for **Middlemac**, the `middlemac-extras` extension for
+Middleman is a great way to add handy developer conveniences to your Middleman
+project.
+
+It serves as a truly “extra” extension that gathers utilities intended for
+**MiddleMac** but are generic enough that they can be used with any Middleman
+project.
+
+This extension currently offers features such as these:
+
+- CSS-based image sizes
+- Automatic Markdown reference-style links
+- Automatic Markdown reference-style images
+- An enhanced `image_tag` that:
+   - Automatically includes a `srcset` attribute for @2x images
+   - Allows you to omit the extension for image files
+   - Fixes `automatic_alt_tags` for absolute path images
+
+* * *
+
+[The `css_image_sizes` helper][css_image_sizes]
+ : Use the `css_image_sizes` helper to specify maximum sizes for all of your
+   project’s images without using unsemantic `width` and `height` attributes
+   in your HTML code.
+
+[The `image_tag` helper][image_tag]
+ : Find out how to use the enhanced `image_tag` helper so that it can be even
+   more helpful.
+
+[The `md_images` helper][md_images]
+ : Automatic Markdown reference style links for every image in your site are
+   available by using this helper.
+
+[The `md_links` helper][md_links]
+ : The `md_links` helper can help you by providing Markdown reference-style
+   links (including `title` attributes) to every page in your site.
+
+[Setting up `config.rb`][config_rb]
+ : Review the key configuration values for making this extension work.
+
+[The MIT License][license]
+ : Describes your legal rights and obligations for using these materials.

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,10 @@
+!!! 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'
+    = stylesheet_link_tag 'css_image_sizes'
+    = javascript_include_tag 'all'
+  %body{:class => "#{page_classes}"}
+    = yield

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

@@ -0,0 +1,22 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-large
+    %div
+      %div
+        = image_tag 'middlemac-extras-small.png', :alt => 'middlemac-extras 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
+
+-#
+  This template is suitable for your landing page or major sections, and features
+  a large version of your logo, the application name, and the application URI.
+  It can include optional :seeAlso content below the application URI.

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

@@ -0,0 +1,20 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-medium
+    %div
+      .yield-content
+        ~ yield
+
+    %div
+      %div
+        = image_tag 'middlemac-extras-small.png', :alt => 'middlemac-extras logo'
+      .related_topics
+        - if content_for?(:seeAlso)
+          %h1 See Also
+          = yield_content :seeAlso
+
+-#
+  This template is suitable for general pages within a group, as it makes
+  navigation between the different pages in the group obvious and easy. It
+  features a medium version of your logo on the right, followed by navigation
+  to the other pages in the group. Optionally :seeAlso content can follow the
+  related pages.

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

@@ -0,0 +1,18 @@
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-small
+    .yield-content
+      = image_tag 'middlemac-extras-small.png', :alt => 'middlemac-extras logo'
+      ~ yield
+
+    .related_topics
+      - if content_for?(:seeAlso)
+        %hr/
+        %h1 See Also
+        = yield_content :seeAlso
+
+-#
+  This template is suitable for general pages that aren’t meant to participate
+  within a group. It does show related pages followed by :seeAlso content at
+  the bottom on the page, but it’s not as obvious for simple navigation as the
+  template-logo-medium. It features a small version of your help logo in the
+  top left, followed by the title.