middleman-pagegroups 1.0.0

data/documentation_project/source/documentation/30_frontmatter.html.md.erb

@@ -0,0 +1,70 @@
+---
+title:     Front Matter
+id:        frontmatter
+blurb:     Front matter controls features such as navigation, and can be used
+           to control page sort order.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+<%= current_page.data.blurb %>
+
+Using some of these new front matter keys will make implementing automatic
+navigation features much, much easier for you. This is a description of the
+keys.
+
+`blurb`
+
+  : Specifying a blurb for your pages make tables of content more interesting,
+    as they can automatically include a brief summary about that particular
+    page. Suitably written blurbs can even be included in their own pages,
+    such as the opening paragraph if this page.
+    
+    Note that if you want HTML features in your blurbs, then they must be
+    written in HTML. Middleman doesn’t process front matter, and so markdown
+    can’t be used.
+    {:.note}
+
+`navigate`
+
+  : When used with group `index.html` pages, it indicates that its legitimate
+    children should implement a page navigator (previous and next page controls)
+    if they are eligible.
+    
+    The default is `false`.
+    
+    As done in this sample documentation project’s templates, a check using
+    the [resource](resources) `current_page.navigator_eligible?` will determine
+    that the group is enabled via `navigate` and then add the navigation control
+    to eligible pages.
+
+`navigator`
+
+  : When used in any of your pages, it indicates that a page navigator (previous
+    and next page controls) should be implemented if the page is eligible. 
+    
+    The default is `true`; this means you only have to use this key to exclude
+    an otherwise legitimate page.
+
+    As done in this sample documentation project’s templates, a check using
+    the [resource](resources) `current_page.navigator_eligible?` will determine
+    that the group is enabled via `navigate` and then add the navigation control
+    to eligible pages.
+
+`order`
+
+  : Use this key to specify the order that the page appears in the various
+    helpers and partials. This key is required for any `index.html` (except for
+    the root item), and optional if you prefer to number your pages using
+    [filename prefixes](directory_organization).
+    
+    All pages eligible for automatic navigation must have an order set via one
+    method or another. Pages without an order are still included, of course,
+    and you can link to them as usual.
+    
+    Sort order is any integer, and sort order does not have to be consecutive.
+    Sometimes it’s helpful to leave large gaps in order to simplify future
+    insertions. (You can use `current_page.page_sequence` to generate page
+    numbers.)

data/documentation_project/source/documentation/40_resources.html.md.erb

@@ -0,0 +1,79 @@
+---
+title:     Resources
+id:        resources
+blurb:     You will use resource methods to design your own partials and templates.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+The built-in resource additions can be useful in designing your own
+partials, templates, and helpers.
+
+## Resources
+
+Resource extensions are usually accessed in your templates, partials, and
+helpers with `current_page`, and so the descriptions below will use this as an
+example. However keep in mind that these methods apply to _any_ resource.
+
+`current_page.breadcrumbs`
+
+  : Returns an array of pages leading to the specified page.
+
+`current_page.brethren`
+
+  : Returns an array of all of the legitimate siblings of the specified page,
+    returning them by ascending sort order.
+
+`current_page.brethren_next`
+
+  : Returns the next legitimate sibling of the specified page, or `nil` if it’s
+    already the last page.
+
+`current_page.brethren_previous`
+
+  : Returns the previous legitimate sibling of the specified page, or `nil` if
+    it’s already the first page.
+
+`current_page.group_count`
+
+  : Indicates the number of pages that are in the current group.
+
+`current_page.legitimate_children`
+
+  : Returns an array of all of the specified page’s legitimate children, sorted
+    in ascending order by their sort order.
+ 
+`current_page.navigator_eligible?`
+
+  : Indicates whether or not the page is eligible for displaying a previous/next
+    page indicator. It’s eligible if all of these conditions are met:
+    
+    - Its parent has front matter key `navigate` set to true.
+    - It does _not_ have a front matter key `navigator` set to false.
+    - It’s a legitimate page, i.e., has a sort order, not ignored, etc.
+
+`current_page.page_group`
+
+  : Indicates the name of the current page group. This can be useful for setting
+    up CSS and performing conditional tasks. The name of the group is simply
+    the name of the containing directory. Group names might not be unique.
+
+`current_page.page_name`
+
+  : Indicates the name of the current page. This can be useful for setting up
+    CSS and performing conditional tasks. The name of the page is simply the
+    output page name without an extension. Page names might not be unique.
+ 
+`current_page.page_sequence`
+
+  : Indicates the sequence of the page within its group, starting with one. You
+    might use this directly as a page number, or use it indirectly if your page
+    numbers don’t start at one.
+    
+    Pages without sort orders will return `nil` for this value.
+
+`current_page.sort_order`
+
+  : Indicates the sort order of the page, or 0 if no order has been assigned.

data/documentation_project/source/documentation/50_helpers.html.md.erb

@@ -0,0 +1,252 @@
+---
+title:     Helpers
+id:        helpers
+blurb:     You will use helpers to design your own partials and templates, and
+           to produce automatic navigation output.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+This extension extends one of Middleman’s built-in helpers, as well as provides
+helpers to access some of the extension defaults within your helpers, partials,
+and pages. Also included are several helpers that generate reasonable automatic
+navigation output into your pages.
+
+## Extended Helpers
+
+Some of Middleman’s built-in helpers are extended in order to offer more
+features.
+
+`page_classes`
+
+  : If you’ve enabled `extend_page_class` in your [`config.rb`](config)
+    file, then `middleman-pagegroups` will add the current `page_name` and
+    `page_group` to the `page_classes` output. Default Middleman project
+    templates include this as the `<body class="…"` content.
+    
+    Here is the result of `page_classes` right now: `<%= page_classes %>`
+
+
+## Access to Extension Configuration Settings
+
+[Configuration settings](config) that are useful for the output-producing
+helpers and for the default partials are exposed via helpers. They are shown
+below, and the current values for this project are shown as an example.
+
+`nav_breadcrumbs_class`
+
+  : Exposes `nav_breadcrumbs_class`, currently `<%= nav_breadcrumbs_class %>`
+
+`nav_breadcrumbs_alt_class`
+
+  : Exposes `nav_breadcrumbs_alt_class`, currently `<%= nav_breadcrumbs_alt_class %>`
+
+`nav_breadcrumbs_alt_label`
+
+  : Exposes `nav_breadcrumbs_alt_label`, currently `<%= nav_breadcrumbs_alt_label %>`
+
+`nav_brethren_class`
+
+  : Exposes `nav_brethren_class`, currently `<%= nav_brethren_class %>`
+
+`nav_brethren_index_class`
+
+  : Exposes `nav_brethren_index_class`, currently `<%= nav_brethren_index_class %>`
+
+`nav_legitimate_children_class`
+
+  : Exposes `nav_legitimate_children_class`, currently `<%= nav_legitimate_children_class %>`
+
+`nav_prev_next_class`
+
+  : Exposes `nav_prev_next_class`, currently `<%= nav_prev_next_class %>`
+
+`nav_prev_next_label_prev`
+
+  : Exposes `nav_prev_next_label_prev`, currently `<%= nav_prev_next_label_prev %>`
+
+`nav_prev_next_label_next`
+
+  : Exposes `nav_prev_next_label_next`, currently `<%= nav_prev_next_label_next %>`
+
+`nav_toc_index_class`
+
+  : Exposes `nav_breadcrumbs_alt_class`, currently `<%= nav_breadcrumbs_alt_class %>`
+
+Note that these are all read-only. These aren’t variables; they’re helpers, and
+they are simply providing a variable value to you.
+{:.note}
+
+## Output Helpers
+
+Output helpers generate most of the automatic navigation features. They’re handy
+to use, but you may consider using the [partials](partials) instead, or writing
+your own.
+
+Each of these helpers accepts an optional parameter called `locals` which, if
+used, must be a hash. For the locals to be useful, the hash must consist of
+useful key value pairs.
+
+All of the helpers accept a `:class` or `:klass` local. If present then the
+navigation feature enclose `div` will be set to that class, otherwise the
+default from your [config.rb](config) will be used.
+
+Middleman geek knowledge: these helpers are implemented internally as partials
+using the same code as used to generate the sample partials, except for
+`nav_toc_index` which has some tricky recursion. This keeps things DRY, and
+is the reason that the parameter is referred to a `locals`. It’s also the
+reason that we have to internally use `klass` instead of `class`.
+{:.note}
+
+For each helper below, the information shown consists of:
+
+  - A brief description of the helper.
+  - A description of the `locals` keys that can be used.
+  - Sample HTML output, generated from using the helper in this project.
+
+* * *
+
+### `nav_breadcrumbs( locals )`
+
+Generate a breadcrumbs structure as an `<ul>`. The trailing element is
+the current page.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+      
+~~~ html
+<%= nav_breadcrumbs %>
+~~~
+
+* * *
+
+### `nav_breadcrumbs_alt( locals )`
+
+Generate the breadcrumbs structure, alternate form, wherein the trailing element
+consists of a label indicating “current page,” as an `<ul>`.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+  
+`:label`
+
+  : Specify the label to use to mark the current page.
+      
+~~~ html
+<%= nav_breadcrumbs_alt %>
+~~~
+
+* * *
+
+### `nav_brethren( locals )`
+
+Generate a fuller list of related topics, including blurbs if present, as a
+`<dl>`.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+
+`:start`
+
+  : The resource from which to start the list, e.g., `current_page` or
+    `current_page.breadcrumbs.first`, or some other resource. The default will
+    always be `current_page` if this local is not declared.
+
+~~~ html
+<%= nav_brethren %>
+~~~
+
+* * *
+
+### `nav_brethren_index( locals )`
+
+Generates a condensed list of brethren, omitting blurbs, as a `<dl>`.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+
+`:start`
+
+  : The resource from which to start the list, e.g., `current_page` or
+    `current_page.breadcrumbs.first`, or some other resource. The default will
+    always be `current_page` if this local is not declared.
+
+~~~ html
+<%= nav_brethren_index %>
+~~~
+
+* * *
+
+### `nav_legitimate_children( locals )`
+
+Generate a fuller list of related topics, including blurbs if present, as a
+`<dl>`.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+
+`:start`
+
+  : The resource from which to start the list, e.g., `current_page` or
+    `current_page.breadcrumbs.first`, or some other resource. The default will
+    always be `current_page` if this local is not declared.
+
+~~~ html
+<%= nav_legitimate_children :start => current_page.breadcrumbs.first %>
+~~~
+
+Because this page has no children at all, the example output above shows output
+using `:start => current_page.breadcrumbs.first`. You will note, though, that
+because it was generated on _this_ page, all of the links appropriately reflect
+the correct path to get to those pages from _here_.
+{:.note}
+
+* * *
+
+### `nav_prev_next( locals )`
+
+Generate a previous and next button as two anchors nested within a `<div>`.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+
+`:label_previous`
+
+  : Label for previous button.
+  
+`:label_next`
+
+  : Label for next button.
+
+~~~ html
+<%= nav_prev_next %>
+~~~
+
+* * *
+
+### `nav_toc_index( locals )`
+
+Generate a nested `<ul>` structure representing the complete table of contents
+from any particular starting point.
+
+`:class`
+
+  : Specify the class of the containing `<div>`.
+
+`:start`
+
+  : The resource from which to start the index, e.g., `current_page` or
+    `current_page.breadcrumbs.first`, or some other resource. The default will
+    always be `current_page` if this local is not declared.
+  
+~~~ html
+<%= nav_toc_index :start => current_page.breadcrumbs.first %>
+~~~

data/documentation_project/source/documentation/60_sample_partials.html.md.erb

@@ -0,0 +1,55 @@
+---
+title:     Sample Partials
+id:        partials
+blurb:     A look at the included sample partials available with <code>middleman-pagegroups</code>.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+Although `middleman-pagegroups` has a useful set of [helpers](helpers), you can
+use its sample partials instead. This gives you the obvious ability to customize
+them to suit your own needs.
+
+For convenience you can find them in this sample project’s `source/partials/`
+directory, or you can generate them on demand if `middleman-pagegroups` gem is
+installed:
+
+~~~ bash
+middleman-pagegroups partials <directory>
+~~~
+
+If you don’t specify a `<directory`> then the files will be placed into your
+current working directory.
+
+## The partials
+
+The partials are named identically to the [helpers of the same name](helpers),
+and they work identically and take the same optional `locals` parameters. For
+details of these partials, the links lead to [Helpers](helpers).
+
+**Caveat**: the `locals` parameters work _almost_ the same. For partials, you
+must **not** use `:class`; use `:klass` instead. This is a limitation due to
+the way that Middleman (really, Padrino) implements partials. These `locals`
+become actual, local variables in the helpers, and the word “class” is not a
+valid local variable name (it’s a reserved word).
+{:.note}
+
+* * *
+
+- [`_nav_breadcrumbs.haml`](helpers.html#navbreadcrumbs-locals-)
+- [`_nav_breadcrumbs_alt.haml`](helpers.html#navbreadcrumbsalt-locals-)
+- [`_nav_brethren_index.haml`](helpers.html#navbrethren-locals-)
+- [`_nav_brethren.haml`](helpers.html#navbrethrenindex-locals-)
+- [`_nav_legitimate_children.haml`](helpers.html#navlegitimatechildren-locals-)
+- [`_nav_prev_next.haml`](helpers.html#navprevnext-locals-)
+- [`_nav_toc_index.haml`](helpers.html#navtocindex-locals-)
+
+* * *
+
+Middleman geek knowledge: when you generate partials using the
+`middleman-pagegroups partials` command, it’s not just a file copy. The partials
+are generated from the same source code that is used by the helpers, except for
+`_nav_toc_index.haml` which has some tricky recursion going on.
+{:.note}

data/documentation_project/source/documentation/70_sample_layouts.html.md.erb

@@ -0,0 +1,92 @@
+---
+title:     Sample Layouts
+id:        layouts
+blurb:     The sample layouts are good models for integrating <code>middleman-pagegroups</code>
+           in your own projects. Let’s have a look.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+To get the most benefit from `middleman-pagegroups` you will most likely want
+to use [partials](partials) and/or [helpers](helpers) in your layouts. This 
+sample project does such.
+
+Let’s examine a couple of examples from this very project.
+
+
+## `template-logo-medium`
+
+Most of this site’s pages use this layout.
+
+~~~ haml
+= wrap_layout ('layout'.to_sym) do
+  .container-logo-medium
+    %div
+      .yield-content
+        ~ yield
+        - if current_page.navigator_eligible?
+          %hr
+          = nav_prev_next
+
+    %div
+      %div
+        = image_tag 'middleman-pagegroups-small.png', :alt => 'middleman-pagegroups logo'
+      .related_topics
+        %h1 Related Topics
+        = nav_brethren_index
+
+        - if content_for?(:seeAlso)
+          %h1 See Also
+          = yield_content :seeAlso
+~~~
+
+We can immediately see that this layout is wrapped by another layout, `layout`,
+that we’ll look at shortly. Within this file are two interesting sections:
+
+~~~ haml
+        - if current_page.navigator_eligible?
+          %hr
+          = nav_prev_next
+~~~
+
+This checks the current page with the `resource.navigator_eligible?` method,
+and then includes the navigation controls using the `nav_prev_next` helper if
+it’s so. This page (the one you’re looking at), includes the navigator controls
+as a result of this code.
+
+Next, this code:
+
+~~~ haml
+        %h1 Related Topics
+        = nav_brethren_index
+~~~
+
+…provides all of the Related Topics for every page of this site using this
+template (which is most of them).
+
+Have a look at `template-logo-large` and `template-logo-small` to find similar
+code.
+
+
+## `layout`
+
+The `layout.haml` provides the outer wrapper for every page of this
+documentation. Aside from providing all of the required HTML boiler plate, it
+contains some interesting code:
+
+~~~ haml
+  %body{:class => "#{page_classes}"}
+    %nav#breadcrumbs
+      = nav_breadcrumbs_alt
+    = yield
+~~~
+
+First, it uses the `page_classes` helper that Middleman projects do by default,
+but in this case the `page_name` and `page_group` will be included. This isn’t
+used by any CSS in this particular project, but it’s available when needed.
+
+Also because this is the outer wrapper for every page, it's a good place to
+add the breadcrumbs navigator at the top of the page, using the
+`nav_breadcrumbs_alt` helper.

data/documentation_project/source/documentation/80_config.html.md.erb

@@ -0,0 +1,98 @@
+---
+title:     Setting up <code>Gemfile</code> and <code>config.rb</code>
+id:        config
+blurb:     Your <code>Gemfile</code> and <code>config.rb</code> files are where
+           you specify your project’s settings.
+layout:    template-logo-medium
+navigator: true
+---
+
+# <%= current_page.data.title %>
+
+Most things happen automatically without any configuration, but as with
+Middleman itself, there are some things to be setup before you can use it.
+
+## `Gemfile`
+
+To ensure that your Middleman project can use `middleman-pagegroups`, make sure
+you add it to your `Gemfile`:
+
+~~~ ruby
+gem 'middleman-pagegroups'
+~~~
+
+## `config.rb`
+
+To use the features provided by `middleman-pagegroups` you have to ensure that
+it’s activated in your `config.rb` file, first:
+
+~~~ ruby
+activate :MiddlemanPageGroups
+~~~
+
+Note that if you are using other Middleman extensions that make modifications to
+the resource list – particularly if they remove things – you will want to ensure
+that they are activated before `:MiddlemanPageGroups`.
+{:.note}
+
+If you are using other Middleman extensions that read from the resource list –
+particularly things that count on correct page locations – you will want to
+ensure that they are activated _after_ `:MiddlemanPageGroups`.
+{:.note}
+
+A more interesting way to active `middleman-pagegroups` is with a block, which
+gives you the opportunity to setup options:
+
+~~~ ruby
+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
+
+~~~
+
+The block above is taken directly from this project’s `config.rb`. The comments
+in the code above describe the purpose of each setting.

data/documentation_project/source/documentation/index.html.md.erb

@@ -0,0 +1,32 @@
+---
+title:    <code>middleman-pagegroups</code> Documentation
+blurb:    Learn how to use <code>middleman-pagegroups</code> to effectively
+          manage large and small projects alike.
+layout:   template-logo-large
+order:    10
+navigate: true
+---
+
+# <%= current_page.data.title %>
+
+<div class="note" markdown="1">
+- All of these documents are part of the `documentation` group. This is because
+  the source directory they reside in is named `documentation/`.
+
+- This particular page is the index page of the group, and is considered the
+  parent of all of the other files.
+  
+  - This page has an `:order` key set; it affects the display order of **its**
+    parent; in this case the parent is the welcome page.  
+
+  - This page has the front matter key `:navigate` set to `true`. This means
+    that the child pages will include **previous** and **next** navigation
+    buttons, unless they have a front matter key `:navigator` set to `false`.
+    
+- Here is [a page](ovum) that's part of the group and is accessible, but is
+  excluded from all of the automatic features.
+</div>
+
+* * *
+
+<%= nav_legitimate_children :class => 'table_contents' %>