middleman-navtree 0.1.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YjU3OWMxZWFiNjE2ZGU5ZmU1Yjc3NzY2NGY1MGZjMTgwMGQ5NGU3YQ==
+  data.tar.gz: !binary |-
+    Y2M0Y2MzZTE1MzZjYjhiYWNkM2MwNGQwZDc5YTk0YTgxN2EzNDA0OQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZTA1ZGZjMzMyYjQ1MDJhOTY1NjBkYzQ0NTU2YWY5NmIxOGFjNDM5ZGRlMDg5
+    NjkxMDAzN2VjZDk0MjRlNWZmMDE1MWVjNTliNzI4YjU1YTJiMzhiZmVmNWE0
+    ZTZhOWM1MTczMjBiZDM3MDY4NGRiMDdjMjk4MjhmZTFlM2RhNTA=
+  data.tar.gz: !binary |-
+    YTBjODk0YTNhODNjMWVjZjU0YmY2NWEzMWQzN2JjOWYwMjA0OTYwNTU3MjJm
+    Mjg1OThlMjVlZjM5ZDFhZGIyMWUzNTUzYmU4NjllY2RlMmZjMDE5ZGU5MWMw
+    YzIwYjNmZWE1MjM2MTViNWRjYmZiY2E3NDg4NzMyYWY5MTAyNmY=

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,86 @@
+# 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.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 :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(/^source/, '') + '/' + 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(/^source/, '') + '/' + 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,131 @@
+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.
+          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, this_resource.url)
+          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.
+      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) fallback to a filename-based-title
+      def discover_title(page = current_page)
+        if page.data.title
+          return page.data.title # Frontmatter title
+        elsif match = page.render({:layout => false}).match(/<h.+>(.*?)<\/h1>/)
+          return match[1]
+        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.1"
+  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.1"
+  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

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: middleman-navtree
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Bryan Braun
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: middleman-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: titleize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: This extension copies the site structure to tree.yml and provides helpers
+  for printing parts of the tree in your middleman templates.
+email:
+- bbraun7@gmail.com
+executables: []
+extensions: []
+extra_rdoc_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
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: For building navigation trees with Middleman
+test_files:
+- features/support/env.rb
+has_rdoc: