middleman-navtree 0.1.2 → 0.1.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OTIzYjU5NmZkYjQ5ZjliZWE2MTYxOTUyODE2OThiNjgzZjdjNjBiYw==
+    YmNiZjE3ZTVjYjJkOTlkZDNhOTlkODcyODczYzg0NDVhMDU3Y2FkZA==
   data.tar.gz: !binary |-
-    NTJkZTFjZTgwODg1OGI0NDQ2N2M4ZDFmNzE1Mzc1MjE5NmIxZjQ3Mg==
+    NDVlYThlYWI0ZTI3MTk5ZGI2ODVlNWY1MzcwYzVjOWQwYzVmMzM4ZA==
 SHA512:
   metadata.gz: !binary |-
-    NDkyYzk1OTY2OGNjMWIzNjk0MWY0ZDQxMzhkOTVjYjUxNjVmZTUxNjNkMDli
-    MTU0NDFiMmEzMmMxNTRmMmI5M2U2YWZjNWMxZTAzMzQzNWQyODQ4YWJkMDQ4
-    NDliZDFmMzE3Y2IwZDQ2YWU3OTQzOWQ1OWJjZTRmNDcwMDQxMWQ=
+    YjI0ZWRjMmVhMTY4ZTZhNjk1Nzk3M2Q0YTg5MDEzMzRlYmEzMmNmMzVlM2Yy
+    ZDk4OTgxMDdkNWEyNWVhZDA0ZWU2NjcxOGI1Y2E4ZGZjODVmYjJkNDVlNTdj
+    NGY5NDg5NGFmMzY2ZjFjMjU2NDc5NDFkNzJkOTFmNGQ1OWRhODI=
   data.tar.gz: !binary |-
-    MGRmNjJjMWMwMzIwY2I5YWY1NGMyZWQ2MGUzZDExYWJmNDE5ZjIzZWFkMDFk
-    MzkyZGNjYzU1Yjc1MWIzZGE4OTM1OWM0OTVhZGMzOTBmZTNlZjQ4NTc5MWJi
-    MzBhNWU4MDI5Njk2NmE1YmViYjEzYjU0OTNjM2VlMWY2NWY2NzM=
+    MWIyN2I5YmVlMWE1NmQxMGYzMTdmZDBjNDE4Y2IxMDk0ZTc5NzA0Njc1MWRm
+    MjE4YmRkZTcwMTQxODM2MTY0OWUzYzFiNmYyNTBmOGJmMDFhZTdjMWM0ZDhi
+    MDZkYjJhOTcwMWZiY2QxMjYxMTgzZTUxMTg3YTZhM2YxOTNlY2U=

data/.gitignore

@@ -0,0 +1,5 @@
+# Ignore bundler lock file
+/Gemfile.lock
+
+# Ignore pkg folder
+/pkg

data/Gemfile

@@ -0,0 +1,19 @@
+# If you have OpenSSL installed, we recommend updating
+# the following line to use "https"
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in middleman-navtree.gemspec
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rdoc'
+  gem 'yard'
+end
+
+group :test do
+  gem 'cucumber'
+  gem 'fivemat'
+  gem 'aruba'
+  gem 'rspec'
+end

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Bryan Braun
+
+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/README.md

@@ -0,0 +1,87 @@
+# Middleman-NavTree
+
+`middleman-navtree` is an extension for the Middleman static site generator that lets you generate navigation trees and menus based on your site structure.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'middleman-navtree'
+
+And then execute:
+
+    $ bundle install
+
+Activate the extension with default options by adding the following to middleman's `config.rb`:
+
+    activate :navtree
+
+Alternatively, you can specify the options you want. Here's an example showing the explicit defaults:
+
+    activate :navtree do |options|
+      options.data_file = 'data/tree.yml' # The data file where our navtree is stored.
+      options.source_dir = 'source' # The `source` directory we want to represent in our nav tree.
+      options.ignore_files = ['sitemap.xml', 'robots.txt'] # An array of files we want to ignore when building our tree.
+      options.ignore_dir = ['assets'] # An array of directories we want to ignore when building our tree.
+      options.home_title = 'Home' # The default link title of the home page (located at "/"), if otherwise not detected.
+      options.promote_files = ['index.html.erb'] # Any files we might want to promote to the front of our navigation
+      options.ext_whitelist = [] # If you add extensions (like '.md') to this array, it builds a whitelist of filetypes for inclusion in the navtree.
+    end
+
+## Usage Examples
+
+When you activate the extension, a tree.yml file will be added to your `data` folder, mimicking your directory structure. Suppose the structure looks like this:
+
+![Directory Structure](screenshots/directory-structure.png)
+
+We can print the entire navigation tree to our template with the `tree_to_html` helper:
+
+    <ul><%= tree_to_html(data.tree) %></ul>
+
+Here's the tree.yml file and the resulting rendered navtree (styled):
+
+![Full tree styled](screenshots/ex1-fulltree.png)
+
+`data.tree` refers to the contents of `/data/tree.yml` (see http://middlemanapp.com/advanced/local-data/ for more information about data files).
+
+You can just as easily print subtrees at any level:
+
+    <ul><%= tree_to_html(data.tree['chapter-1']) %></ul>
+
+![Subtree styled](screenshots/ex2-subtree.png)
+
+    <ul><%= tree_to_html(data.tree['chapter-1']['exercises']) %></ul>
+
+![Subsubtree styled](screenshots/ex3-subsubtree.png)
+
+A second paramter allows you to limit the depth of your trees and subtrees:
+
+    <ul><%= tree_to_html(data.tree, 2) %></ul>
+
+![Full tree with depth limit styled](screenshots/ex4-depthlimit.png)
+
+You can combine both techniques to print menus at any level, with a specific depth:
+
+    <ul><%= tree_to_html(data.tree['chapter-1'], 1) %></ul>
+
+![Subtree with depth limit styled](screenshots/ex5-subtree_and_depthlimit.png)
+
+Another helper in the gem allows you to add next/previous links for paginating
+through the tree. For example:
+
+    <%= previous_link(data.tree) %> <%= next_link(data.tree) %>
+
+![Styled next/previous links](screenshots/previous-next.png)
+
+You can likewise limit pagination to a specific subtree:
+
+    <%= previous_link(data.tree['chapter-2']) %><%= next_link(data.tree['chapter-2']) %>
+
+
+## Contributing
+
+1. Fork the project
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to your github repository (git push origin my-new-feature)
+5. Submit a Pull Request

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:cucumber, 'Run features that should pass') do |t|
+  t.cucumber_opts = "--color --tags ~@wip --strict --format #{ENV['CUCUMBER_FORMAT'] || 'Fivemat'}"
+end
+
+require 'rake/clean'
+
+task :test => ['cucumber']
+
+task :default => :test

data/features/support/env.rb

@@ -0,0 +1,4 @@
+PROJECT_ROOT_PATH = File.dirname(File.dirname(File.dirname(__FILE__)))
+require 'middleman-core'
+require 'middleman-core/step_definitions'
+require File.join(PROJECT_ROOT_PATH, 'lib', 'middleman-navtree')

data/lib/middleman-navtree.rb

@@ -0,0 +1,14 @@
+# Require core library
+require 'middleman-core'
+require 'middleman-navtree/version'
+
+# Register extensions which can be activated
+# Make sure we have the version of Middleman we expect
+# Name param may be omited, it will default to underscored
+# version of class name
+
+
+::Middleman::Extensions.register(:navtree) do
+    require "middleman-navtree/extension"
+      ::Middleman::NavTree::NavTreeExtension
+end

data/lib/middleman-navtree/extension.rb

@@ -0,0 +1,144 @@
+require 'middleman-navtree/helpers'
+
+module Middleman
+  module NavTree
+
+    # Extension namespace
+    # @todo: Test the extension against a vanilla Middleman install.
+    # @todo: Test the extension against a middleman-blog install.
+    class NavTreeExtension < ::Middleman::Extension
+      # All the options for this extension
+      option :source_dir, 'source', 'The directory our tree will begin at.'
+      option :data_file, 'data/tree.yml', 'The file we will write our directory tree to.'
+      option :ignore_files, ['sitemap.xml', 'robots.txt'], 'A list of filenames we want to ignore when building our tree.'
+      option :ignore_dir, ['assets'], 'A list of directory names we want to ignore when building our tree.'
+      option :home_title, 'Home', 'The default link title of the home page (located at "/"), if otherwise not detected.'
+      option :promote_files, ['index.html.erb'], 'A list of files you want to push to the front of the tree (if they exist).'
+      option :ext_whitelist, [], 'A whitelist of filename extensions (post-render) that we are allowing in our navtree. Example: [".html"]'
+
+      # Helpers for use within templates and layouts.
+      self.defined_helpers = [ ::Middleman::NavTree::Helpers ]
+
+      def initialize(app, options_hash={}, &block)
+        # Call super to build options from the options_hash
+        super
+
+        # Require libraries only when activated
+        require 'yaml'
+        require 'titleize'
+
+        @existing_promotes = []
+
+      end
+
+      def after_configuration
+        # Add the user's config directories to the "ignore_dir" option because
+        # these are all things we won't need printed in a NavTree.
+        options.ignore_dir << app.settings.js_dir
+        options.ignore_dir << app.settings.css_dir
+        options.ignore_dir << app.settings.fonts_dir
+        options.ignore_dir << app.settings.images_dir
+        options.ignore_dir << app.settings.helpers_dir
+        options.ignore_dir << app.settings.layouts_dir
+        options.ignore_dir << app.settings.partials_dir
+
+        # Build a hash out of our directory information
+        tree_hash = scan_directory(options.source_dir, options)
+
+        # Promote any promoted files to the beginning of our hash.
+        tree_hash = promote_files(tree_hash, options)
+
+        # Write our directory tree to file as YAML.
+        # @todo: This step doesn't rebuild during live-reload, which causes errors if you move files
+        #        around during development. It may not be that hard to set up. Low priority though.
+        IO.write(options.data_file, YAML::dump(tree_hash))
+      end
+
+
+      # Method for storing the directory structure in a hash.
+      # @todo: the order of the data is defined by the order in the hash, and technically, ruby hashes
+      #        are unordered. This may be more robust if I defined an ordered hash type similar to
+      #        this one in Rails: http://apidock.com/rails/ActiveSupport/OrderedHash
+      def scan_directory(path, options, name=nil)
+        data = {}
+        Dir.foreach(path) do |filename|
+
+          # Check to see if we should skip this file. We skip invisible files
+          # (starts with "."), ignored files, and promoted files (which are
+          # handled later in the process).
+          next if (filename[0] == '.')
+          next if (filename == '..' || filename == '.')
+          next if options.ignore_files.include? filename
+
+          if options.promote_files.include? filename
+            original_path = path.sub(/^#{options.source_dir}/, '') + '/' + filename
+            @existing_promotes << original_path
+            next
+          end
+
+          full_path = File.join(path, filename)
+          if File.directory?(full_path)
+            # This item is a directory.
+            # Check to see if we should ignore this directory.
+            next if options.ignore_dir.include? filename
+
+            # Loop through the method again.
+            data.store(filename, scan_directory(full_path, options, filename))
+          else
+
+            # This item is a file.
+            if !options.ext_whitelist.empty?
+              # Skip any whitelisted extensions.
+              next unless options.ext_whitelist.include? File.extname(filename)
+            end
+
+            original_path = path.sub(/^#{options.source_dir}/, '') + '/' + filename
+            data.store(filename, original_path)
+          end
+        end
+
+        return data
+      end
+
+      # Method for appending promoted files to the front of our source tree.
+      # @todo: Currently, options.promote_files only expects a filename, which means that
+      #        if multiple files in different directories have the same filename, they
+      #        will both be promoted, and one will not appear (due to the 'no-two-identical
+      #        -indices-in-a-hash' rule).
+      # @todo: This system also assumes filenames only have a single extension,
+      #        which may not be the case (like index.html.erb)
+      # @todo: Basically, this is not elegent at all.
+      def promote_files(tree_hash, options)
+
+        if @existing_promotes.any?
+          ordered_matches = []
+
+          # The purpose of this loop is to get my list of existing promotes
+          # in the order specified in the options array, so it can be promoted
+          # properly.
+          options.promote_files.each do |filename|
+            # Get filename without extension (index.md => index)
+            filename_without_ext = filename.chomp(File.extname(filename))
+            # Test against each existing_promote, and store matches
+            @existing_promotes.each do |pathname|
+              # Get another filename without extension from the pathname (/book/index.html => index)
+              pathname_without_ext = File.basename(pathname, ".*")
+              # Add matches to our ordered matches array.
+              if filename_without_ext == pathname_without_ext
+                ordered_matches << [filename, pathname]
+              end
+            end
+          end
+          # Promote all files found in both the promotes list and the file structure. This is an array
+          # of arrays
+          ordered_matches.reverse.each do |match|
+            tree_hash = Hash[match[0], match[1]].merge!(tree_hash)
+          end
+        end
+
+        return tree_hash
+      end
+
+    end
+  end
+end

data/lib/middleman-navtree/helpers.rb

@@ -0,0 +1,137 @@
+module Middleman
+  module NavTree
+    # NavTree-related helpers that are available to the Middleman application in +config.rb+ and in templates.
+    module Helpers
+
+      #  A recursive helper for converting source tree data from into HTML
+      def tree_to_html(value, depth = Float::INFINITY, key = nil, level = 0)
+        html = ''
+
+        if value.is_a?(String)
+          # This is a child item (a file). Get the Sitemap resource for this file.
+          # note: sitemap.extensionless_path converts the path to its 'post-build' extension.
+          this_resource = sitemap.find_resource_by_path(sitemap.extensionless_path(value))
+          # Define string for active states.
+          active = this_resource == current_page ? 'active' : ''
+          title = discover_title(this_resource)
+          link = link_to(title, sitemap.extensionless_path(value))
+          html << "<li class='child #{active}'>#{link}</li>"
+        else
+          # This is a directory.
+          if key.nil?
+            # The first level is the source directory, so it has no key and needs no list item.
+            value.each do |newkey, child|
+              html << tree_to_html(child, depth, newkey, level + 1)
+            end
+          # Continue rendering deeper levels of the tree, unless restricted by depth.
+          elsif depth >= (level + 1)
+            # This directory has a key and should be listed in the page hieararcy with HTML.
+            dir_name = key
+            html << "<li class='parent'><span class='parent-label'>#{dir_name.gsub(/-/, ' ').gsub(/_/, ' ').titleize}</span>"
+            html << '<ul>'
+
+            # Loop through all the directory's contents.
+            value.each do |newkey, child|
+              html << tree_to_html(child, depth, newkey, level + 1)
+            end
+            html << '</ul>'
+            html << '</li>'
+          end
+        end
+
+        return html
+      end
+
+      # Pagination helpers
+      # @todo: One potential future feature is previous/next links for paginating on a
+      #        single level instead of a flattened tree. I don't need it but it seems pretty easy.
+      def previous_link(sourcetree)
+        pagelist = flatten_source_tree(sourcetree)
+        position = get_current_position_in_page_list(pagelist)
+        # Skip link generation if position is nil (meaning, the current page isn't in our
+        # pagination pagelist).
+        if position
+          prev_page = pagelist[position - 1]
+          options = {:class => "previous"}
+          unless first_page?(pagelist)
+            link_to("Previous", prev_page, options)
+          end
+        end
+      end
+
+      def next_link(sourcetree)
+        pagelist = flatten_source_tree(sourcetree)
+        position = get_current_position_in_page_list(pagelist)
+        # Skip link generation if position is nil (meaning, the current page isn't in our
+        # pagination pagelist).
+        if position
+          next_page = pagelist[position + 1]
+          options = {:class => "next"}
+          unless last_page?(pagelist)
+            link_to("Next", next_page, options)
+          end
+        end
+      end
+
+      # Helper for use in pagination methods.
+      def first_page?(pagelist)
+        return true if get_current_position_in_page_list(pagelist) == 0
+      end
+
+      # Helper for use in pagination methods.
+      def last_page?(pagelist)
+        return true if pagelist[get_current_position_in_page_list(pagelist)] == pagelist[-1]
+      end
+
+      # Method to flatten the source tree, for use in pagination methods.
+      # Note, I could do this with a lot less code using Glob. I should refactor
+      # in the future. See http://stackoverflow.com/a/2370823/1154642.
+      def flatten_source_tree(value, k = [], level = 0, flat_tree = [])
+
+        if value.is_a?(String)
+          # This is a child item (a file).
+          flat_tree.push(sitemap.extensionless_path(value))
+        elsif value.is_a?(Hash)
+          # This is a parent item (a directory).
+          value.each do |key, child|
+            flatten_source_tree(child, key, level + 1, flat_tree)
+          end
+        end
+
+        return flat_tree
+      end
+
+      # Helper for use in pagination methods.
+      def get_current_position_in_page_list(pagelist)
+        pagelist.each_with_index do |page_path, index|
+          if page_path == "/" + current_page.path
+            return index
+          end
+        end
+        # If we reach this line, the current page path wasn't in our page list and we'll
+        # return false so the link generation is skipped.
+        return FALSE
+      end
+
+      # Utility helper for getting the page title
+      # Based on this: http://forum.middlemanapp.com/t/using-heading-from-page-as-title/44/3
+      # 1) Use the title from frontmatter metadata, or
+      # 2) peek into the page to find the H1, or
+      # 3) Use the home_title option (if this is the home page--defaults to "Home"), or
+      # 4) fallback to a filename-based-title
+      def discover_title(page = current_page)
+        if page.data.title
+          return page.data.title # Frontmatter title
+        elsif page.url == '/'
+          return extensions[:navtree].options[:home_title]
+        elsif match = page.render({:layout => false}).match(/<h.+>(.*?)<\/h1>/)
+          return match[1] # H1 title
+        else
+          filename = page.url.split(/\//).last.titleize
+          return filename.chomp(File.extname(filename))
+        end
+      end
+
+    end
+  end
+end

data/lib/middleman-navtree/version.rb

@@ -0,0 +1,5 @@
+module Middleman
+  module NavTree
+    VERSION = "0.1.3"
+  end
+end

data/lib/middleman_extension.rb

@@ -0,0 +1 @@
+require 'middleman-navtree'

data/middleman-navtree.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "middleman-navtree"
+  s.version     = "0.1.3"
+  s.licenses    = ['MIT']
+  s.date        = Date.today.to_s
+
+  s.summary     = "For building navigation trees with Middleman"
+  s.description = "This extension copies the site structure to tree.yml and provides helpers for printing parts of the tree in your middleman templates."
+
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Bryan Braun"]
+  s.email       = ["bbraun7@gmail.com"]
+  s.homepage    = "https://github.com/bryanbraun/middleman-navtree"
+
+  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 this extension depends on.
+  s.add_runtime_dependency("middleman-core", ["~> 3.3"])
+  s.add_runtime_dependency("titleize", ["~> 1.3"])
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: middleman-navtree
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Bryan Braun
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-26 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: middleman-core
@@ -45,7 +45,26 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- features/support/env.rb
+- lib/middleman-navtree.rb
+- lib/middleman-navtree/extension.rb
+- lib/middleman-navtree/helpers.rb
+- lib/middleman-navtree/version.rb
+- lib/middleman_extension.rb
+- middleman-navtree.gemspec
+- screenshots/directory-structure.png
+- screenshots/ex1-fulltree.png
+- screenshots/ex2-subtree.png
+- screenshots/ex3-subsubtree.png
+- screenshots/ex4-depthlimit.png
+- screenshots/ex5-subtree_and_depthlimit.png
+- screenshots/previous-next.png
 homepage: https://github.com/bryanbraun/middleman-navtree
 licenses:
 - MIT
@@ -70,5 +89,6 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: For building navigation trees with Middleman
-test_files: []
+test_files:
+- features/support/env.rb
 has_rdoc: