middlemac-extras 1.0.0

data/documentation_project/source/stylesheets/_normalize.scss

@@ -0,0 +1,374 @@
+/*! normalize.css v2.0.1 | MIT License | git.io/normalize */
+
+/* ==========================================================================
+   HTML5 display definitions
+   ========================================================================== */
+
+/*
+ * Corrects `block` display not defined in IE 8/9.
+ */
+
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+nav,
+section,
+summary {
+    display: block;
+}
+
+/*
+ * Corrects `inline-block` display not defined in IE 8/9.
+ */
+
+audio,
+canvas,
+video {
+    display: inline-block;
+}
+
+/*
+ * Prevents modern browsers from displaying `audio` without controls.
+ * Remove excess height in iOS 5 devices.
+ */
+
+audio:not([controls]) {
+    display: none;
+    height: 0;
+}
+
+/*
+ * Addresses styling for `hidden` attribute not present in IE 8/9.
+ */
+
+[hidden] {
+    display: none;
+}
+
+/* ==========================================================================
+   Base
+   ========================================================================== */
+
+/*
+ * 1. Sets default font family to sans-serif.
+ * 2. Prevents iOS text size adjust after orientation change, without disabling
+ *    user zoom.
+ */
+
+html {
+    font-family: sans-serif; /* 1 */
+    -webkit-text-size-adjust: 100%; /* 2 */
+    -ms-text-size-adjust: 100%; /* 2 */
+}
+
+/*
+ * Removes default margin.
+ */
+
+body {
+    margin: 0;
+}
+
+/* ==========================================================================
+   Links
+   ========================================================================== */
+
+/*
+ * Addresses `outline` inconsistency between Chrome and other browsers.
+ */
+
+a:focus {
+    outline: thin dotted;
+}
+
+/*
+ * Improves readability when focused and also mouse hovered in all browsers.
+ */
+
+a:active,
+a:hover {
+    outline: 0;
+}
+
+/* ==========================================================================
+   Typography
+   ========================================================================== */
+
+/*
+ * Addresses `h1` font sizes within `section` and `article` in Firefox 4+,
+ * Safari 5, and Chrome.
+ */
+
+h1 {
+    font-size: 2em;
+}
+
+/*
+ * Addresses styling not present in IE 8/9, Safari 5, and Chrome.
+ */
+
+abbr[title] {
+    border-bottom: 1px dotted;
+}
+
+/*
+ * Addresses style set to `bolder` in Firefox 4+, Safari 5, and Chrome.
+ */
+
+b,
+strong {
+    font-weight: bold;
+}
+
+/*
+ * Addresses styling not present in Safari 5 and Chrome.
+ */
+
+dfn {
+    font-style: italic;
+}
+
+/*
+ * Addresses styling not present in IE 8/9.
+ */
+
+mark {
+    background: #ff0;
+    color: #000;
+}
+
+
+/*
+ * Corrects font family set oddly in Safari 5 and Chrome.
+ */
+
+code,
+kbd,
+pre,
+samp {
+    font-family: monospace, serif;
+    font-size: 1em;
+}
+
+/*
+ * Improves readability of pre-formatted text in all browsers.
+ */
+
+pre {
+    white-space: pre;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}
+
+/*
+ * Sets consistent quote types.
+ */
+
+q {
+    quotes: "\201C" "\201D" "\2018" "\2019";
+}
+
+/*
+ * Addresses inconsistent and variable font size in all browsers.
+ */
+
+small {
+    font-size: 80%;
+}
+
+/*
+ * Prevents `sub` and `sup` affecting `line-height` in all browsers.
+ */
+
+sub,
+sup {
+    font-size: 75%;
+    line-height: 0;
+    position: relative;
+    vertical-align: baseline;
+}
+
+sup {
+    top: -0.5em;
+}
+
+sub {
+    bottom: -0.25em;
+}
+
+/* ==========================================================================
+   Embedded content
+   ========================================================================== */
+
+/*
+ * Removes border when inside `a` element in IE 8/9.
+ */
+
+img {
+    border: 0;
+}
+
+/*
+ * Corrects overflow displayed oddly in IE 9.
+ */
+
+svg:not(:root) {
+    overflow: hidden;
+}
+
+/* ==========================================================================
+   Figures
+   ========================================================================== */
+
+/*
+ * Addresses margin not present in IE 8/9 and Safari 5.
+ */
+
+figure {
+    margin: 0;
+}
+
+/* ==========================================================================
+   Forms
+   ========================================================================== */
+
+/*
+ * Define consistent border, margin, and padding.
+ */
+
+fieldset {
+    border: 1px solid #c0c0c0;
+    margin: 0 2px;
+    padding: 0.35em 0.625em 0.75em;
+}
+
+/*
+ * 1. Corrects color not being inherited in IE 8/9.
+ * 2. Remove padding so people aren't caught out if they zero out fieldsets.
+ */
+
+legend {
+    border: 0; /* 1 */
+    padding: 0; /* 2 */
+}
+
+/*
+ * 1. Corrects font family not being inherited in all browsers.
+ * 2. Corrects font size not being inherited in all browsers.
+ * 3. Addresses margins set differently in Firefox 4+, Safari 5, and Chrome
+ */
+
+button,
+input,
+select,
+textarea {
+    font-family: inherit; /* 1 */
+    font-size: 100%; /* 2 */
+    margin: 0; /* 3 */
+}
+
+/*
+ * Addresses Firefox 4+ setting `line-height` on `input` using `!important` in
+ * the UA stylesheet.
+ */
+
+button,
+input {
+    line-height: normal;
+}
+
+/*
+ * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
+ *    and `video` controls.
+ * 2. Corrects inability to style clickable `input` types in iOS.
+ * 3. Improves usability and consistency of cursor style between image-type
+ *    `input` and others.
+ */
+
+button,
+html input[type="button"], /* 1 */
+input[type="reset"],
+input[type="submit"] {
+    -webkit-appearance: button; /* 2 */
+    cursor: pointer; /* 3 */
+}
+
+/*
+ * Re-set default cursor for disabled elements.
+ */
+
+button[disabled],
+input[disabled] {
+    cursor: default;
+}
+
+/*
+ * 1. Addresses box sizing set to `content-box` in IE 8/9.
+ * 2. Removes excess padding in IE 8/9.
+ */
+
+input[type="checkbox"],
+input[type="radio"] {
+    box-sizing: border-box; /* 1 */
+    padding: 0; /* 2 */
+}
+
+/*
+ * 1. Addresses `appearance` set to `searchfield` in Safari 5 and Chrome.
+ * 2. Addresses `box-sizing` set to `border-box` in Safari 5 and Chrome
+ *    (include `-moz` to future-proof).
+ */
+
+input[type="search"] {
+    -webkit-appearance: textfield; /* 1 */
+    -moz-box-sizing: content-box;
+    -webkit-box-sizing: content-box; /* 2 */
+    box-sizing: content-box;
+}
+
+/*
+ * Removes inner padding and search cancel button in Safari 5 and Chrome
+ * on OS X.
+ */
+
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration {
+    -webkit-appearance: none;
+}
+
+/*
+ * Removes inner padding and border in Firefox 4+.
+ */
+
+button::-moz-focus-inner,
+input::-moz-focus-inner {
+    border: 0;
+    padding: 0;
+}
+
+/*
+ * 1. Removes default vertical scrollbar in IE 8/9.
+ * 2. Improves readability and alignment in all browsers.
+ */
+
+textarea {
+    overflow: auto; /* 1 */
+    vertical-align: top; /* 2 */
+}
+
+/* ==========================================================================
+   Tables
+   ========================================================================== */
+
+/*
+ * Remove most spacing between table cells.
+ */
+
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}

data/documentation_project/source/stylesheets/css_image_sizes.css.erb

@@ -0,0 +1 @@
+<%= css_image_sizes %>

data/documentation_project/source/stylesheets/style.css.scss

@@ -0,0 +1,3 @@
+@import "normalize";              // keep normalize in case deployment to non Help Center.
+@import "middlemac_minimal";      // basic styles.
+@import "github";                 // styles used for code blocks.

data/lib/middlemac-extras/extension.rb

@@ -0,0 +1,261 @@
+################################################################################
+# extension.rb
+#  This file constitutes the framework for the bulk of this extension.
+################################################################################
+require 'middleman-core'
+require 'pathname'
+require 'fastimage'
+
+class MiddlemacExtras < ::Middleman::Extension
+
+  ############################################################
+  # Define the options that are to be set within `config.rb`
+  # as extension options.
+  ############################################################
+  option :retina_srcset, true, 'If true then the image_tag helper will be extended to include automatic @2x images.'
+  option :img_auto_extensions, true, 'If true then `image_tag` will work without filename extensions.'
+  option :img_auto_extensions_order, %w(.svg .png .jpg .jpeg .gif .tiff .tif), 'Specifies the order to support automatic image extensions.'
+
+
+  ############################################################
+  # initialize
+  ############################################################
+  def initialize(app, options_hash={}, &block)
+
+    super
+
+    @md_links_b = nil
+    @md_images_b = nil
+    @md_sizes_b = nil
+
+  end # initialize
+
+
+  ############################################################
+  # after_configuration
+  #  Callback occurs before `before_build`.
+  #############################################################
+  def after_configuration
+
+    # Reset the helpers' buffers when the configuration
+    # 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_images_b = nil
+    @md_sizes_b = nil
+
+  end
+
+
+  ############################################################
+  #  Helpers
+  #    Methods defined in this helpers block are available in
+  #    templates.
+  ############################################################
+
+  helpers do
+
+    #--------------------------------------------------------
+    # md_links
+    #   Adds simple markdown links where needed.
+    #--------------------------------------------------------
+    def md_links
+      extensions[:MiddlemacExtras].md_links_b
+    end
+
+
+    #--------------------------------------------------------
+    # md_images
+    #   Adds simple markdown image links where needed.
+    #--------------------------------------------------------
+    def md_images
+      extensions[:MiddlemacExtras].md_images_b
+    end
+
+
+    #--------------------------------------------------------
+    # css_image_sizes
+    #   Generates image size CSS information for all images.
+    #--------------------------------------------------------
+    def css_image_sizes
+      extensions[:MiddlemacExtras].md_sizes_b
+    end
+
+
+    #--------------------------------------------------------
+    # 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.
+    #--------------------------------------------------------
+    def image_tag(path, params={})
+      params.symbolize_keys!
+      ext_options = extensions[:MiddlemacExtras].options
+
+      img_auto_extensions = ext_options[:img_auto_extensions]
+      img_auto_extensions = params.delete(:img_auto_extensions) if params[:img_auto_extensions]
+
+      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
+      # specified name + :img_auto_extensions_order is found,
+      # use that instead.
+      #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+      if File.extname(path) == '' && img_auto_extensions
+        ext_options[:img_auto_extensions_order].reverse.each do |ext|
+          real_path = "#{path.dup}#{ext}"
+          real_path = if path.start_with?('/')
+                        File.expand_path(File.join(@app.config[:source], real_path))
+                      else
+                        File.expand_path(File.join(@app.config[:source], @app.config[:images_dir], real_path))
+                      end
+
+          file = app.files.find(:source, real_path)
+          if file && file[:full_path].exist?
+            path = "#{path.dup}#{ext}"
+          end
+        end # each
+      end
+
+
+      #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+      # Support automatic @2x image srcset.
+      #- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+      if retina_srcset
+        test_path = path.sub(/#{File.extname(path)}/i, "@2x#{File.extname(path)}")
+        real_path = if path.start_with?('/')
+                      File.expand_path(File.join(@app.config[:source], test_path))
+                    else
+                      File.expand_path(File.join(@app.config[:source], @app.config[:images_dir], test_path))
+                    end
+
+        file = app.files.find(:source, real_path)
+        if file && file[:full_path].exist?
+          params[:srcset] ||= "#{test_path} 2x"
+        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
+
+
+  end #helpers
+
+
+
+  ############################################################
+  #  Instance Methods
+  ############################################################
+
+  #--------------------------------------------------------
+  # md_links_b
+  #   Adds simple markdown links where needed.
+  #--------------------------------------------------------
+  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]}\"" }
+                        .join("\n")
+    end
+
+    @md_links_b
+  end
+
+
+  #--------------------------------------------------------
+  # md_images_b
+  #--------------------------------------------------------
+  def md_images_b
+    unless @md_images_b
+      @md_images_b = get_link_data('image/')
+                         .collect { |l| "[#{l[:reference]}]: #{l[:link]}" }
+                         .join("\n")
+    end
+    @md_images_b
+  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.
+  #--------------------------------------------------------
+  def get_link_data( *types )
+    all_links = []
+    # We'll include a sort by number of path components in this chain so
+    # that we can improve the chances of higher-level items not having
+    # naming conflicts. For example, the topmost index.html file should
+    # not require a prefix!
+    app.sitemap.resources
+        .select { |r| r.content_type && r.content_type.start_with?( *types ) }
+        .sort { |a, b| Pathname(a.destination_path).each_filename.to_a.count <=> Pathname(b.destination_path).each_filename.to_a.count }
+        .each do |r|
+      reference_path = Pathname(r.destination_path).each_filename.to_a.reverse
+      reference_path.shift
+      reference = File.basename(r.destination_path, '.*').gsub(%r{ }, '_')
+      link = r.url
+      title = r.data.title ? r.data.title.gsub(%r{</?[^>]+?>}, '') : nil
+
+      i = 0
+      while all_links.find { |link| link[:reference] == reference }
+        next_piece = reference_path[i].gsub(%r{ }, '_')
+        reference = "#{next_piece}-#{reference}"
+        i += 1
+      end
+
+      all_links << {:reference => reference, :link => link, :title => title}
+    end # .each
+
+    all_links
+  end
+
+
+  #--------------------------------------------------------
+  # md_sizes_b
+  #  For every image resource, try to build the size.
+  #--------------------------------------------------------
+  def md_sizes_b
+    unless @md_sizes_b
+      @md_sizes_b = []
+      app.sitemap.resources
+          .select { |r| r.content_type && r.content_type.start_with?('image/') }
+          .each do |r|
+
+        file = r.file_descriptor.full_path
+        base_name = File.basename(r.destination_path, '.*')
+        factor = 1
+        factor = 2 if base_name.end_with?('@2x')
+        factor = 3 if base_name.end_with?('@3x')
+        if FastImage.size(file)
+          width = (FastImage.size(file)[0] / factor).to_i.to_s
+          height = (FastImage.size(file)[1] / factor).to_i.to_s
+          @md_sizes_b << "img[src$='#{r.url}'] { max-width: #{width}px; max-height: #{height}px; }"
+        end
+      end # each
+    end
+
+    @md_sizes_b.join("\n")
+  end
+
+end # class MiddlemacExtras

data/lib/middlemac-extras/version.rb

@@ -0,0 +1,5 @@
+module Middleman
+    module MiddlemacExtras
+        VERSION = '1.0.0'
+    end
+end

data/lib/middlemac-extras.rb

@@ -0,0 +1,6 @@
+require 'middleman-core'
+
+Middleman::Extensions.register :MiddlemacExtras, :before_configuration do
+  require_relative 'middlemac-extras/extension'
+  MiddlemacExtras
+end

data/middlemac-extras.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'middlemac-extras/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'middlemac-extras'
+  s.version     = Middleman::MiddlemacExtras::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Jim Derry']
+  s.email       = ['balthisar@gmail.com']
+  s.homepage    = 'https://github.com/middlemac/middlemac-extras'
+  s.summary     = 'Implements several useful developer conveniences for Middleman projects.'
+  s.description = 'Implements several useful developer conveniences for Middleman projects.'
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+  
+  # The version of middleman-core your extension depends on
+  s.add_runtime_dependency('middleman-core', ['~> 4.1', '>= 4.1.6'])
+
+  # Additional dependencies
+  s.add_runtime_dependency('middleman-cli', ['~> 4.1', '>= 4.1.6'])
+  s.add_runtime_dependency('fastimage', ['~> 1.9', '>= 1.9.0'])
+end