middleman-pagegroups 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d0f5bd96df68bc910b528cbaae3a2d6ee49f769
+  data.tar.gz: 3458d3fbb6bd11fc50b6901c1233e7e8c13bf3d9
+SHA512:
+  metadata.gz: 1ee3edf96541e2d7b09464b23bcdd493e82033fe75fe9cc6a6baa73c165fe9f246704e1974058c01c5e1c7f6aa62e44cc022a4700f9b0857b3baecdf09fd2330
+  data.tar.gz: 62448847f7f368f721f56db215c98c80c45f17ad93f96a861f5d653edf442b637603534682e56205d3f8c50044abb92f81050e84c849e1ab92e9dd6a27acfb19

data/.gitignore

@@ -0,0 +1,17 @@
+# Rubymine noise
+.idea/
+
+# BBedit noise
+*.bbprojectd
+
+# Mac OS X noise
+.DS_Store
+
+# Ignore bundler lock files
+Gemfile.lock
+
+# Ignore pkg folder
+/pkg
+
+# Ignore build folders
+build*

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+middleman-pagegroups change log
+===============================
+
+- Version 1.0 / 2016-March
+
+  - Initial Release

data/Gemfile

@@ -0,0 +1,18 @@
+# If you do not have OpenSSL installed, update
+# the following line to use "http://" instead
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in middleman-pagegroups.gemspec
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rdoc'
+  gem 'yard'
+end
+
+group :test do
+  gem 'cucumber'
+  gem 'aruba'
+  gem 'rspec'
+end

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License
+===============
+
+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/README.md

@@ -0,0 +1,87 @@
+middleman-pagegroups readme
+---------------------------
+[![Gem Version](https://badge.fury.io/rb/middleman-targets.svg)](https://badge.fury.io/rb/middleman-targets)
+
+
+`middleman-pagegroups`
+
+ : This gem provides advanced navigation tools and helpers for grouping pages
+   by topic and navigating between them. It includes support for tables of
+   content, related pages, breadcrumbs, and more.
+
+   It is standalone and can be used in any Middleman project.
+
+
+Install the Gem
+---------------
+
+Install the gem in your preferred way, typically:
+
+~~~ bash
+gem install middleman-pagegroups
+~~~
+
+From git source:
+
+~~~ bash
+rake install
+~~~
+
+
+Documentation
+-------------
+
+The complete documentation leverages the features of this gem in order to better
+document them. Having installed the gem, read the full documentation in your
+web browser:
+
+~~~ bash
+middleman-pagegroups documentation
+cd middleman-pagegroups-docs/
+bundle install
+bundle exec middleman server
+~~~
+   
+And then open your web browser to the address specified (typically
+`localhost:4567`).
+
+
+Quick Documentation
+-------------------
+
+[Middleman](https://middlemanapp.com/) 4.1.6 or newer is required. Earlier
+point versions of Middleman do not have the necessary support for this
+extension.
+
+Once setup and configured, you can build multiple targets like so:
+
+TO-DO
+
+
+Added Features
+--------------
+
+TO-DO
+
+
+Middlemac
+---------
+
+This Middleman extension is a critical part of
+[Middlemac](https://github.com/middlemac), the Mac OS X help building system
+for Mac OS X applications. However this gem is not Mac OS X specific and can be
+useful in any application for which you want to provide structure and
+navigation.
+
+
+License
+-------
+
+MIT. See `LICENSE.md`.
+
+
+Changelog
+---------
+
+See `CHANGELOG.md` for point changes, or simply have a look at the commit
+history for non-version changes (such as readme updates).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :spec

data/bin/middleman-pagegroups

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+
+################################################################################
+# middleman-pagegroups
+#  This file constitutes the command line interface for middleman-pagegroups
+################################################################################
+
+require 'thor'
+require 'fileutils'
+require_relative '../lib/middleman-pagegroups/version'
+require_relative '../lib/middleman-pagegroups/partials'
+
+
+module MiddlemanPageGroupsCli
+
+  class Cli < Thor
+
+    map %w[--version -v] => :__print_version
+
+    ############################################################
+    # help
+    #  Override to add additional description.
+    ############################################################
+    def help(*args)
+      if args.count == 0
+        puts <<-HEREDOC
+
+middleman-pagegroups version #{Middleman::MiddlemanPageGroups::VERSION}
+
+This gem adds functionality to Middleman and is not executable on its own,
+other than for generating the documentation sample project and sample partial
+files. Instead, you must add this gem to your Middleman project's `Gemfile` 
+and then activate it in your `config.rb` file. 
+
+HEREDOC
+      end
+      super
+    end
+
+
+    ############################################################
+    # documentation
+    ############################################################
+    desc 'documentation', 'Install the sample project into your current working directory.'
+    long_desc <<-HEREDOC
+`documentation` will produce a sample project named `middleman-pagegroups-docs/`
+in your current working directory. This sample uses the features of this gem.
+You can then serve this new project to read the documentation by:
+
+cd middleman-pagegroups-docs
+bundle install
+bundle exec middleman server
+    
+    HEREDOC
+    def documentation
+      source = File.join('..', '..', 'documentation_project', '.')
+      source = File.expand_path(source, __FILE__)
+      dest = File.expand_path(File.join('.', 'middleman-pagegroups-docs', '.'))
+      FileUtils.cp_r(source, dest)
+      puts "middleman-pagegroups installed the project in\n#{dest}" 
+    end
+
+
+    ############################################################
+    # partials
+    ############################################################
+    desc 'partials [<directory>]', 'Install the sample partials.'
+    long_desc <<-HEREDOC
+`partials` will produce sample partial files into your current working
+directory, or into <directory> if you specify one. These partials can
+then be used using Middleman's `partials` helper in your own projects.
+    
+    HEREDOC
+    def partials(*args)
+      dest = File.expand_path( args.empty? ? File.join('.') : args[0] )
+      unless File.writable?( dest )
+        puts "middleman-pagegroups can't seem to write to #{dest}."
+        exit 1
+      end
+
+      MMPartials::MM_PARTIALS.each do |p|
+        filename = File.join( dest, p[:filename] )
+        puts "writing #{filename}"
+        File.open( filename, 'w' ) { |f| f.write( p[:content]) }
+      end
+
+      puts "middleman-pagegroups installed #{MMPartials::MM_PARTIALS.count} partials in\n#{dest}"
+    end
+
+
+    ############################################################
+    # __print_version
+    ############################################################
+    desc '--version, -v', 'print the version'
+    def __print_version
+      puts "middleman-pagegroups version #{Middleman::MiddlemanPageGroups::VERSION}"
+    end
+
+  end # class Cli
+
+end # module MiddlemanPagegroupsCli
+
+
+###########################################################
+# Main
+###########################################################
+
+MiddlemanPageGroupsCli::Cli.start(ARGV)

data/documentation_project/.gitignore

@@ -0,0 +1,25 @@
+# Rubymine noise
+.idea/
+
+# BBedit noise
+*.bbprojectd
+
+# Mac OS X noise
+.DS_Store
+
+# Ignore bundler lock files
+Gemfile.lock
+
+# Ignore pkg folder
+/pkg
+
+# Ignore build folders
+.rbenv-*
+.ruby-gemset
+.ruby-version
+.sass-cache
+.sassc
+.tmp
+build*
+Makefile
+tmp

data/documentation_project/Gemfile

@@ -0,0 +1,18 @@
+# If you do not have OpenSSL installed, change
+# the following line to use 'http://'
+source 'https://rubygems.org'
+
+# For faster file watcher updates on Windows:
+gem 'wdm', '~> 0.1.0', platforms: [:mswin, :mingw]
+
+# Windows does not come with time zone data
+gem 'tzinfo-data', platforms: [:mswin, :mingw, :jruby]
+
+# Middleman Gems
+gem 'middleman-pagegroups', :path => '../'
+gem 'middleman', '~> 4.1.6'
+gem 'middleman-syntax'
+
+
+#gem 'middleman-compass'
+gem 'font-awesome-sass'

data/documentation_project/README.md

@@ -0,0 +1,13 @@
+documentation-project readme
+----------------------------
+
+This gem's documentation is a Middleman project using the features of this gem.
+To view the documentation project, `cd` into this directory and
+
+~~~ bash
+gem install
+bundle exec middleman serve
+~~~
+
+When the server starts, it will provide instructions on how to view the project
+in your web browser.

data/documentation_project/config.rb

@@ -0,0 +1,109 @@
+################################################################################
+# Sample Project for middleman-pagegroups
+################################################################################
+
+#==========================================================================
+# Conflicting resources
+#  middleman-pagegroups uses Middleman's resource map to determine
+#  relationships between pages in groups. Be sure to activate other
+#  extensions that might manipulate the resource map before activating
+#  middleman-pagegroups, such as MiddlemanTargets.
+#==========================================================================
+# activate :MiddlemanTargets
+
+
+#==========================================================================
+# Extension Setup
+#  Note that middleman-targets adds configuration parameters to the base
+#  Middleman application (supported feature in 4.0+); there are *not*
+#  extension options. Additionally if middleman-targets is in your Gemfile
+#  then it is also activated automatically.
+#==========================================================================
+activate :MiddlemanPageGroups do |config|
+
+  # Indicate whether or not numeric file name prefixes used for sorting
+  # pages should be eliminated during output. This results in cleaner
+  # URI's. Helpers such as `page_name` and Middleman helpers such as
+  # `page_class` will reflect the pretty name.
+  config.strip_file_prefixes = true
+
+  # Indicates whether or not Middleman's built-in `page_class` helper is
+  # extended to include the page_group and page_name.
+  config.extend_page_class = true
+
+  # the following options provide defaults for the built-in helpers, and
+  # also work with the sample partials if you choose to install them.
+  # They'll also work in your own partials and helpers, of course.
+
+  # Default css class for the nav_breadcrumbs helper/partial.
+  config.nav_breadcrumbs_class = 'breadcrumbs'
+
+  # Default css class for the nav_breadcrumbs_alt helper/partial.
+  config.nav_breadcrumbs_alt_class = 'breadcrumbs'
+
+  # Default "current page" label for the nav_breadcrumbs_alt helper/partial.
+  config.nav_breadcrumbs_alt_label = 'Current page'
+
+  # Default css class for the nav_brethren helper/partial.
+  config.nav_brethren_class = 'table_contents'
+
+  # Default css class for the nav_brethren_index helper/partial.
+  config.nav_brethren_index_class = 'related-topics'
+
+  # Default css class for the nav_legitimate_children helper/partial.
+  config.nav_legitimate_children_class = 'table_contents'
+
+  # Default css class for the nav_prev_next helper/partial.
+  config.nav_prev_next_class = 'navigate_prev_next'
+
+  # Default "previous" label text for the nav_prev_next helper/partial.
+  config.nav_prev_next_label_prev = 'Previous'
+
+  # Default "next" label text for the nav_prev_next helper/partial.
+  config.nav_prev_next_label_next = 'Next'
+
+  # Default css class for the nav_toc_index helper/partial.
+  config.nav_toc_index_class = 'help_map'
+
+end
+
+
+#==========================================================================
+# Regular Middleman Setup
+#==========================================================================
+
+set :relative_links, true
+activate :syntax
+
+
+#==========================================================================
+# Helpers
+#  These helpers are used by the sample project only; there's no need
+#  to keep them around in your own projects.
+#==========================================================================
+
+# Methods defined in the helpers block are available in templates
+helpers do
+
+  def product_name
+    'middleman-pagegroups'
+  end
+
+  def product_version
+    '1.0.0'
+  end
+
+  def product_uri
+    'https://github.com/middlemac'
+  end
+
+end
+
+# Build-specific configuration
+configure :build do
+  # Minify CSS on build
+  # activate :minify_css
+
+  # Minify Javascript on build
+  # activate :minify_javascript
+end

data/documentation_project/source/documentation/10_concepts.html.md.erb

@@ -0,0 +1,111 @@
+---
+title:     Concepts
+id:        concepts
+blurb:     Understand the design and philosophy of <code>middleman-pagegroups</code>.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+This section describes some of `middleman-pagegroups`’ design and
+philosophy, and this is the right section to begin in if you’re still wondering
+what this extension actually provides to you.
+
+## Intended Uses
+
+`middleman-pagegroups` is chiefly designed to support hierarchical, structured,
+multi-page documents that have organizational relationships between them, such
+as product manuals, help files, and Middleman extension gem documentation.
+
+Using its model for groups, pages, legitimate children, and brethren simplifies
+the implementation of tables of contents, previous and next buttons, breadcrumb
+indicators, see-also tables, and more. This frees you from having to manually
+update and validate scores of links and hand-coding on a page-by-page basis.
+
+Books with sections, chapters, and pages are an obvious sample use case.
+Software manuals, tutorials, training courses, and more are all suitable
+candidates for the flexible and nearly-automatic organization provided by
+`middleman-pagegroups`.
+
+
+## What `middleman-pagegroups` does
+
+`middleman-pagegroups` principally enables **automatic navigation** via the
+management of **sort order**, **groups** (including nested groups), and making
+a determination about the **legitimacy** of these relationships.
+
+It provides helpers and sample partials to enable **breadcrumbs**, **previous**
+and *next** buttons, **tables of contents**, and **related pages**, all using
+the concepts that enable automatic navigation.
+
+
+## Convention over Configuration
+
+All of the features making `middleman-pagegroups` useful hinge on being able to
+enable automatic navigation, and this is accomplished by following logical,
+simple conventions that avoid having to micromanage many series of configuration
+files.
+
+For example you will define a **group** as a directory in your file system and
+include an `index.html` file to serve as the parent of that group.
+
+You will establish **sort orders** to define the **legitimacy** of certain
+pages for inclusion or exclusion in the automatic navigation system.
+
+
+## Hierarchical Design
+
+`middleman-pagegroups` inherently uses the concept of “groups,” each of which
+has pages and/or groups that belong to the group as its children.
+
+Every project has a single, top-level (root) group, and because groups are named
+for the directory that contain them, the top level group is usually named
+`source` (because Middleman’s default source folder is so-named).
+
+A detailed look at the hierarchical design and requirements can be found in the
+[Directory Organization](directory_organization) section.
+ 
+ 
+## Sort Order
+
+Every page intended for automatic navigation must include a sort order, which
+can be specified with a [Front Matter](frontmatter) key or as part of the file
+name.
+
+Don’t confuse sort order with page number. Sort order is simply an integer value
+that does not have to be consecutive. It may be convenient to specify these in
+steps of 10, for example, to make later insertions easier.
+
+To include pages in your project (such as [this one](ovum)) that don’t
+participate in the automatic navigation scheme, simply do not provide a sort
+order.
+
+
+## Legitimacy
+
+In the context of `middleman-pagegroups` “legitimacy” refers to eligibility for
+inclusion in the automatic navigation system. The criteria for legitimacy
+include:
+
+- The file must be an HTML or XHTML file.
+- The file must not be `ignored?`, which is a resource attribute built into
+  Middleman. Other extensions (such as `middleman-targets`) may modify this
+  attribute.
+- The file must have an assigned sort order.
+
+You can still include accessible pages within the group but exclude them from
+the automatic navigation features, i.e., render them “illegitimate.” Simply do
+not provide a sort order for these pages.
+
+
+## Brethren
+
+`middleman-pagegroups` uses the word _brethren_ to refer to _legitimate
+siblings_, i.e., “legitimate” as described above, not including itself. This
+serves as a good basis for related-pages types of links.
+
+## Legitimate Children
+
+`middleman-pagegroups` similarly refines Middleman’s built-in children to
+ensure that _only_ “legitimate” documents are included in automatic navigation.

data/documentation_project/source/documentation/20_directory_organization.html.md.erb

@@ -0,0 +1,85 @@
+---
+title:     Directory and File Organization
+id:        directory_organization
+blurb:     Organized directory structures enable most of the automatic features
+           of <code>middleman-pagegroups</code>.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+Directory organization is one of key parts of letting `middleman-pagegroups`
+take the hassle out of managing content for you.
+
+Briefly the role of the directory layout convention is this:
+
+- Directories equate to groups.
+- Directory names equate to the group names.
+- Each file in a directory, except for `index.html`, constitutes a member of
+  the group.
+- The `index.html` file in a directory serves as the placeholder for the
+  `parent` of the group.
+
+
+Each group must include at least one file that will render into `index.html`.
+This file serves as the parent to the group. As such, the top-level document
+of any project is `source/html.index` which is a familiar expectation in any
+HTML project, and the default, top-level document for any nested directory is
+also `index.html`, which is consistent with practices to which you are no doubt
+already accustomed.
+
+One important novelty of `middleman-pagegroups` is that a group’s `index.html`
+file is considered a child of parent group. For example in this documentation
+project’s hierarchy…
+
+~~~
+source/
+  index.html         <- root object, parent to license, toc, and documentation/index.html
+  license.html       <- Sort order is 20. Member of the `source` group.
+  toc.html           <- Sort order is 30. Member of the `source` group.
+  documentation/
+    index.html       <- Sort order is 10, and is a member of the `source` group!
+    concepts.html
+    directory_organization.html
+    …
+~~~
+
+…the files `license.html`, `toc.html`, and `documentation/index.html` are _all_
+children of the `source` group. The file `source/index.html` is the child of
+no one; it is the root document.
+
+Another way to look at this is like this: the directory `documentation/`, i.e.,
+the group `documentation`, is a member of the `source` group. It’s represented
+by its `index.html` file.
+{:.note}
+
+
+## Nesting
+
+Groups can be arbitrarily nested as deep as you wish. There’s probably a limit
+that would cause a stack overflow and crash, but you’re not likely to reach it
+unless you try deliberately.
+
+
+## Sort Order
+
+Although [Front Matter](frontmatter) is an appropriate place to specify a
+page’s `:order`, it’s sometimes convenient for developers to arrange files in
+order in their filesystem, too. This is supported by `middleman-pagegroups`,
+too.
+
+Simply prefix your filename with any integer followed by an underscore, e.g.,
+the source file for this page is `20_directory_organization.html.md.erb`.
+
+In order to avoid ugly URIs (e.g., `20_directory_organization.html`) make sure
+that your [`config.rb`](config) file sets `strip_file_prefixes` to `true`, which
+will rewrite page names without the order specifiers (e.g.,
+`directory_organization.html`).
+
+Filename sort order prefixes only work for non-group files, however. Groups and
+their `index.html` files cannot be magically numbered in this way. You _must_
+use the front matter `:order` key in `index.html` files, instead.
+{:.note}
+
+Front matter `:order` will override any order specified by file names.