middleman-pagegroups 1.0.2 → 1.0.3

data/documentation_project/source/documentation/100_nested_folder/one_file.html.md.erb

@@ -0,0 +1,11 @@
+---
+title:    One File
+blurb:    This is just a file with a sort order of 20 specified in its front
+          matter.
+layout:   template-logo-medium
+order:    20
+---
+
+# <%= current_page.data.title %>
+
+<%= current_page.data.blurb %>

data/documentation_project/source/documentation/100_nested_folder/stray.txt

@@ -0,0 +1,6 @@
+Stray.txt
+---------
+
+This is just a non-rendered file that's tagging along for the ride. It
+demonstrates that non-page numbered assets are put into the proper directory
+when the directory is renamed.

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

@@ -36,7 +36,7 @@ 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
+and **next** buttons, **tables of contents**, and **related pages**, all using
 the concepts that enable automatic navigation.
 
 

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

@@ -22,11 +22,12 @@ Briefly the role of the directory layout convention is this:
   `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
+Each group must include at least one file that will render into `index.html` (or
+whatever your `config[:index_file]` is for the more advanced among you). 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`
@@ -69,17 +70,18 @@ page’s `:order`, it’s sometimes convenient for developers to arrange files i
 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`.
+Simply prefix your filename (including group directories) 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.
+Filename sort order prefixes do not work on `index.html` files for a group; use
+a sort order prefix on its enclosing directory instead. The sample
+`nested_folder` in this project is numbered in this way.
 {:.note}
 
 Front matter `:order` will override any order specified by file names.

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

@@ -8,72 +8,7 @@ navigator: true
 
 # <%= current_page.data.title %>
 
-The built-in resource additions can be useful in designing your own
-partials, templates, and helpers.
+The built-in resource extensions can be useful in designing your own
+partials, templates, and helpers, and are usually accessed within them.
 
-## 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.
+<%= partial 'partials/yard_resources' %>

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

@@ -14,71 +14,32 @@ 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
+This extension extends **Middleman** built-in helpers in order to offer more
 features.
 
-`page_classes`
+<%= partial 'partials/yard_helpers_extended' %>
 
-  : 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 %>`
+The current value of `page_classes` is "`<%= page_classes %>`".
 
+* * *
 
-## Access to Extension Configuration Settings
+## Helpers to Access 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`
+helpers and for the default partials are exposed via helpers.
 
-  : 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 %>`
+<%= partial 'partials/yard_helpers_css' %>
 
 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
@@ -89,9 +50,9 @@ 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.
+All of the helpers accept a `:klass` local. If present then the navigation
+feature enclosing `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
@@ -100,104 +61,46 @@ 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.
+<%= partial 'partials/yard_helpers' %>
 
 * * *
 
-### `nav_breadcrumbs( locals )`
+## Output Helpers’ Examples
 
-Generate a breadcrumbs structure as an `<ul>`. The trailing element is
-the current page.
+The examples below illustrate the output of each of the output helpers as they
+are generated on this very page.
 
-`:class`
-
-  : Specify the class of the containing `<div>`.
-      
+<dl class="examples_list">
+  <dt>nav_breadcrumbs</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_breadcrumbs %>
 ~~~
+  </dd>
 
-* * *
-
-### `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.
-      
+  <dt>nav_breadcrumbs_alt</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_breadcrumbs_alt %>
 ~~~
+  </dd>
 
-* * *
-
-### `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.
-
+  <dt>nav_brethren</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_brethren %>
 ~~~
+  </dd>
 
-* * *
-
-### `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.
-
+  <dt>nav_brethren_index</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_brethren_index %>
 ~~~
+  </dd>
 
-* * *
-
-### `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.
-
+  <dt>nav_legitimate_children</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_legitimate_children :start => current_page.breadcrumbs.first %>
 ~~~
@@ -207,46 +110,21 @@ 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}
+  </dd>
 
-* * *
-
-### `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.
 
+  <dt>nav_prev_next</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_prev_next %>
 ~~~
+  </dd>
 
-* * *
-
-### `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.
-  
+  <dt>nav_toc_index</dt>
+  <dd markdown="1">
 ~~~ html
 <%= nav_toc_index :start => current_page.breadcrumbs.first %>
 ~~~
+  </dd>
+</dl>

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

@@ -25,28 +25,29 @@ 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-)
-
-* * *
+The partials are named identically to the [output helpers of the same name]
+(helpers), and they work identically and take the same optional `locals`
+parameters. For details of these partials, the refer to the to
+[Helpers](helpers) section.
+
+For reference, the list of partials is below:
+
+- `_nav_breadcrumbs.haml`
+- `_nav_breadcrumbs_alt.haml`
+- `_nav_brethren_index.haml`
+- `_nav_brethren.haml`
+- `_nav_legitimate_children.haml`
+- `_nav_prev_next.haml`
+- `_nav_toc_index.haml`
+
+As per standard **Middleman** conventions, partials’ names begin with an
+underscore to prevent the partial file _per se_ from being output in the build;
+it is not necessary to include the underscore (or the file extension) when using
+the `partial` helper. For example:
+
+~~~ erb
+<%%= partial 'partials/nav_breadcrumbs' %>
+~~~
 
 Middleman geek knowledge: when you generate partials using the
 `middleman-pagegroups partials` command, it’s not just a file copy. The partials