middlemac-extras 1.0.6 → 1.0.11

data/features/support/env.rb

@@ -0,0 +1,20 @@
+PROJECT_ROOT_PATH = File.dirname(File.dirname(File.dirname(__FILE__)))
+ENV['TEST'] = 'true'
+
+require 'middleman'
+require 'middleman-core/step_definitions'
+require File.join(PROJECT_ROOT_PATH, 'lib', 'middlemac-extras')
+
+
+require 'cucumber/formatter/pretty'
+class QuietFormatter < Cucumber::Formatter::Pretty
+  def initialize(runtime, io, options)
+     $stderr = File.new( '/dev/null', 'w' )
+    super(runtime, io, options)
+  end
+  
+  def after_features(features)
+    $stderr = STDOUT
+    super(features)
+  end
+end

data/fixtures/middlemac_extras_app/config.rb

@@ -0,0 +1,7 @@
+activate :MiddlemacExtras do |config|
+  config.retina_srcset = true
+  config.img_auto_extensions = true
+  config.img_auto_extensions_order = %w(.svg .png .jpg .jpeg .gif .tiff .tif)
+end
+
+set :relative_links, true

data/fixtures/middlemac_extras_app/source/index.html.md.erb

@@ -0,0 +1,31 @@
+---
+title: Fixture for middlemac-extras
+---
+# css_image_sizes
+
+~~~
+<%= css_image_sizes %>
+~~~
+
+# md_images
+
+~~~
+<%= md_images %>
+~~~
+
+# md_links
+
+~~~
+<%= md_links %>
+~~~
+
+# extended image_tag
+
+~~~
+<%= image_tag 'middlemac-extras-small' %>
+~~~
+
+~~~
+<%= image_tag 'middlemac-extras-smaller' %>
+~~~
+

data/lib/middlemac-extras/extension.rb

@@ -1,11 +1,12 @@
-################################################################################
-# extension.rb
-#  This file constitutes the framework for the bulk of this extension.
-################################################################################
 require 'middleman-core'
 require 'pathname'
 require 'fastimage'
 
+################################################################################
+# This extension provides Middleman several useful helpers and extends some of
+# its built-in helpers to offer more features.
+# @author Jim Derry <balthisar@gmail.com>
+################################################################################
 class MiddlemacExtras < ::Middleman::Extension
 
   ############################################################
@@ -17,14 +18,46 @@ class MiddlemacExtras < ::Middleman::Extension
   option :img_auto_extensions_order, %w(.svg .png .jpg .jpeg .gif .tiff .tif), 'Specifies the order to support automatic image extensions.'
 
 
+  # @!group Extension Configuration
+
+  # @!attribute [rw] options[:retina_srcset]=
+  # This option determines whether or not the enhanced `image_tag` helper will
+  # be used to include an @2x `srcset` attribute automatically. This automatic
+  # behavior will only be applied if the image asset exists on disk and this
+  # option is set to `true`.
+  # @param [Boolean] value `true` or `false` to enable or disable this feature.
+  # @return [Boolean] Returns the current value of this option.
+
+  # @!attribute [rw] options[:img_auto_extensions]=
+  # This option determines whether or not to support specifying images without
+  # using a file name extension. 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`.
+  # @param [Boolean] value `true` or `false` to enable or disable this feature.
+  # @return [Boolean] Returns the current value of this option.
+
+  # @!attribute [rw] options[:img_auto_extensions_order]=
+  # This option defines the eligible file name extensions and their precedence
+  # when you specify an image without an extension using the `image_tag` helper.
+  # Set this to an array of image file extensions in your desired order of
+  # of precedence.
+  # @param [Array<String>] value Set to an array of image extensions.
+  # @return [Array<String>] Returns the current value of this option.
+
+  # @!endgroup
+
+
   ############################################################
   # initialize
+  # @visibility private
   ############################################################
   def initialize(app, options_hash={}, &block)
 
     super
 
     @md_links_b = nil
+    @md_links_modern_b = nil
     @md_images_b = nil
     @md_sizes_b = nil
 
@@ -33,7 +66,8 @@ class MiddlemacExtras < ::Middleman::Extension
 
   ############################################################
   # after_configuration
-  #  Callback occurs before `before_build`.
+  #   Callback occurs before `before_build`.
+  # @visibility private
   #############################################################
   def after_configuration
 
@@ -41,6 +75,7 @@ class MiddlemacExtras < ::Middleman::Extension
     # changes. For speed we don't want to recalculate everything
     # every time a helper is used, but only the first time.
     @md_links_b = nil
+    @md_links_modern_b = nil
     @md_images_b = nil
     @md_sizes_b = nil
 
@@ -56,8 +91,13 @@ class MiddlemacExtras < ::Middleman::Extension
   helpers do
 
     #--------------------------------------------------------
-    # md_links
-    #   Adds simple markdown links where needed.
+    # This helper provides access to `middlemac-extras`’ 
+    # index of links in Markdown reference format, enabling
+    # you to use reference-style links in documents. Because
+    # this helper includes literal Markdown, it’s only useful
+    # in Markdown documents.
+    # @return [String] Returns a string with the Markdown
+    #   index of every page in your project.
     #--------------------------------------------------------
     def md_links
       extensions[:MiddlemacExtras].md_links_b
@@ -65,8 +105,29 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # md_images
-    #   Adds simple markdown image links where needed.
+    # This helper provides access to `middlemac-extras`’ 
+    # index of links in Markdown reference format, enabling
+    # you to use reference-style links in documents. Because
+    # this helper includes literal Markdown, it’s only useful
+    # in Markdown documents. This is only useful when using
+    # Middlemac 3.0.0 or newer, which includes support for
+    # helpbook style links.
+    # @return [String] Returns a string with the Markdown
+    #   index of every page in your project.
+    #--------------------------------------------------------
+    def md_hblinks
+      extensions[:MiddlemacExtras].md_links_modern_b
+    end
+
+
+    #--------------------------------------------------------
+    # This helper provides access to `middlemac-extras`’ 
+    # index of images in Markdown reference format, enabling
+    # you to use reference-style images in documents. Because
+    # this helper includes literal Markdown, it’s only useful
+    # in Markdown documents.
+    # @return [String] Returns a string with the Markdown
+    #   index of every image in your project.
     #--------------------------------------------------------
     def md_images
       extensions[:MiddlemacExtras].md_images_b
@@ -74,8 +135,14 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # css_image_sizes
-    #   Generates image size CSS information for all images.
+    # This helper provides CSS for every image in your
+    # project. Each image will have a declaration that sets
+    # `max-width` and `max-height` to the actual size of the
+    # image. Proper @2x image support is included. It’s most
+    # useful to use this helper in a `some_file.css.erb`
+    # file.
+    # @return [String] Returns a string with the CSS markup
+    #   for every image found in your project.
     #--------------------------------------------------------
     def css_image_sizes
       extensions[:MiddlemacExtras].md_sizes_b
@@ -83,10 +150,25 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # image_tag(path, params={})
-    #   Add automatic srcset if an @2x image is present and
-    #   no srcset is already specified. Also support the
-    #   use of extension-less images.
+    # With the proper options enabled this helper extends
+    # the built-in functionality of **Middleman**’s helpers
+    # in a couple of ways. With `:retina_srcset` enabled,
+    # automatic `srcset` attributes will be applied to
+    # `<img>` tags if an @2x version of the specified image
+    # is found. With `:img_auto_extensions` it’s possible to
+    # specify image names without the file name extension.
+    # @param [String] path Specify path to the image file.
+    # @param [Hash] params Optional parameters to pass to
+    #   the helper. **Middleman** (and other extensions)
+    #   provide other parameters in addition to these.
+    # @option params [Boolean] :img_auto_extensions Allows
+    #   control of the automatic image extensions option
+    #   on a per-use basis.
+    # @option params [Boolean] :retina_srcset Allows control
+    #   of the automatic @2x images feature on a per-use
+    #   basis. 
+    # @return [String] Returns an HTML `<img>` tag.
+    # @group Extended Helpers
     #--------------------------------------------------------
     def image_tag(path, params={})
       params.symbolize_keys!
@@ -100,9 +182,6 @@ class MiddlemacExtras < ::Middleman::Extension
       retina_srcset = ext_options[:retina_srcset]
       retina_srcset = params.delete(:retina_srcset) if params[:retina_srcset]
 
-      automatic_alt_tags = @app.extensions[:automatic_alt_tags]
-      automatic_alt_tags = params.delete(:automatic_alt_tags) if params[:automatic_alt_tags]
-
 
       #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       # Support images without extensions. If an image with the
@@ -154,19 +233,6 @@ class MiddlemacExtras < ::Middleman::Extension
         end
       end
 
-
-      #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-      # Support automatic alt tags for absolute locations, too.
-      # Only do this for absolute paths; let the extension do its
-      # own thing otherwise.
-      #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-      if automatic_alt_tags && path.start_with?('/')
-        alt_text = File.basename(path, '.*')
-        alt_text.capitalize!
-        params[:alt] ||= alt_text
-      end
-
-
       super(path, params)
     end
 
@@ -176,17 +242,28 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
   ############################################################
-  #  Instance Methods
+  # Instance Methods
+  # @!group Instance Methods
   ############################################################
 
-  #--------------------------------------------------------
-  # md_links_b
-  #   Adds simple markdown links where needed.
-  #--------------------------------------------------------
+
+  #########################################################
+  # This accessor for @md_links_b lazily populates the
+  # backing variable and buffers it for repeated use. In
+  # the event of file changes, a server restart is needed.
+  # @returns [String] Returns the Markdown reference list.
+  # @!visibility private
+  #########################################################
   def md_links_b
     unless @md_links_b
       @md_links_b = get_link_data('text/html', 'application/xhtml')
-                        .collect { |l| "[#{l[:reference]}]: #{l[:link]} \"#{l[:title]}\"" }
+                        .collect { |l| 
+                          if l[:title]
+                            "[#{l[:reference]}]: #{l[:link]} \"#{l[:title]}\"" 
+                          else
+                            "[#{l[:reference]}]: #{l[:link]}" 
+                          end
+                          }
                         .join("\n")
     end
 
@@ -194,9 +271,38 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # md_images_b
-  #--------------------------------------------------------
+  #########################################################
+  # This accessor for @md_links_modern_b lazily populates
+  # the backing variable and buffers it for repeated use.
+  # In the event of file changes, a server restart is 
+  # needed.
+  # @returns [String] Returns the Markdown reference list.
+  # @!visibility private
+  #########################################################
+  def md_links_modern_b
+    unless @md_links_modern_b
+      @md_links_modern_b = get_link_data('text/html', 'application/xhtml')
+                          .collect { |l| 
+                            if l[:title]
+                              "[#{l[:reference]}]: #{l[:hb_link]} \"#{l[:title]}\"" 
+                            else
+                              "[#{l[:reference]}]: #{l[:hb_link]}" 
+                            end
+                            }
+                          .join("\n")
+    end
+
+    @md_links_modern_b
+  end
+
+
+  #########################################################
+  # This accessor for @md_images_b lazily populates the
+  # backing variable and buffers it for repeated use. In
+  # the event of file changes, a server restart is needed.
+  # @returns [String] Returns the Markdown reference list.
+  # @!visibility private
+  #########################################################
   def md_images_b
     unless @md_images_b
       @md_images_b = get_link_data('image/')
@@ -207,13 +313,15 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # get_link_data( *types )
-  #   Get all of the required link data for generating
-  #   markdown shortcuts.
-  # @param  types should be the content_type to check.
-  # @return an array of hashes with file data.
-  #--------------------------------------------------------
+  #########################################################
+  # Get all of the required link data for generating
+  # markdown shortcuts for the two property accessors.
+  # @param [va_list<String>] types One or more MIME types
+  #   specifying the file types for which to build links.
+  # @return [Array<Hash>] An array of hashes containing
+  #   the file data.
+  # @!visibility private
+  #########################################################
   def get_link_data( *types )
     all_links = []
     # We'll include a sort by number of path components in this chain so
@@ -228,6 +336,7 @@ class MiddlemacExtras < ::Middleman::Extension
       reference_path.shift
       reference = File.basename(r.destination_path, '.*').gsub(%r{ }, '_')
       link = r.url
+      hb_link = defined?(r.hb_NavId) ? "#/#{r.hb_NavId}" : nil
       title = r.data.title ? r.data.title.gsub(%r{</?[^>]+?>}, '') : nil
 
       i = 0
@@ -237,17 +346,21 @@ class MiddlemacExtras < ::Middleman::Extension
         i += 1
       end
 
-      all_links << {:reference => reference, :link => link, :title => title}
+      all_links << {:reference => reference, :link => link, :title => title, :hb_link => hb_link}
     end # .each
 
     all_links
   end
 
 
-  #--------------------------------------------------------
-  # md_sizes_b
-  #  For every image resource, try to build the size.
-  #--------------------------------------------------------
+  #########################################################
+  # For every image resource in the project, attempt to
+  # build the CSS rules. Only bitmap images are supported,
+  # as vectors (e.g., SVG) don’t have a specific size.
+  # @returns [String] Returns the CSS stylesheet with the
+  #   maximum width and height for each image.
+  # @!visibility private
+  #########################################################
   def md_sizes_b
     unless @md_sizes_b
       @md_sizes_b = []
@@ -282,11 +395,19 @@ class MiddlemacExtras < ::Middleman::Extension
   end
   
   
-  #--------------------------------------------------------
-  # with_extension_proposal( path, ext )
-  #  Returns a file with an extension if found; otherwise
-  #  it returns the original file.
-  #--------------------------------------------------------
+  #########################################################
+  # Returns a file with an extension if found; otherwise
+  # it returns the original file. This is used to search
+  # for images for which no file name extension has been
+  # provided.
+  # @param [String] path Specifies the image without an
+  #   extension, which is to be checked.
+  # @param [String] ext Specifies the extension to check.
+  # @returns [String] Returns the path of the image with
+  #   an extension (if found), or returns the original
+  #   `path` parameter.
+  # @!visibility private
+  #########################################################
   def with_extension_proposal( path, ext )
     return path unless File.extname(path) == '' && app.extensions[:MiddlemacExtras].options[:img_auto_extensions]
   
@@ -311,10 +432,15 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # say
-  #  Output colored messages using ANSI codes.
-  #--------------------------------------------------------
+  #########################################################
+  # Output colored messages using ANSI codes.
+  # @param [String] message The message to output to the
+  #   console.
+  # @param [Symbol] color The color in which to display
+  #   the message.
+  # @returns [Void]
+  # @!visibility private
+  #########################################################
   def say(message = '', color = :reset)
     colors = { :blue   => "\033[34m",
                :cyan   => "\033[36m",

data/lib/middlemac-extras/version.rb

@@ -1,5 +1,5 @@
 module Middleman
     module MiddlemacExtras
-        VERSION = '1.0.6'
+        VERSION = '1.0.11'
     end
 end