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.

Top Level Namespace

Defined Under Namespace

Classes: MiddlemanPageGroups

Class: MiddlemanPageGroups

Inherits:
Middleman::Extension
  • Object
show all
Defined in:
lib/middleman-pagegroups/extension.rb

Overview

This extension 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.

Author:

Extension Configuration (collapse)

Extended Helpers (collapse)

Helpers (collapse)

CSS Class Helpers (collapse)

Resource Extensions (collapse)

Instance Attribute Details

- (Boolean) options[:extend_page_class]=(value)

If true then the default Middleman page_class helper will be extended to include simple group and page_name for each resource.

Parameters:

  • value (Boolean)

    true or false to enable or disable this feature.

Returns:

  • (Boolean)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 41

- (String) options[:nav_breadcrumbs_alt_class]=(value)

Default css class for the nav_breadcrumbs_alt helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 53

- (String) options[:nav_breadcrumbs_alt_label]=(value)

Default “current page” label for the nav_breadcrumbs_alt helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 59

- (String) options[:nav_breadcrumbs_class]=(value)

Default css class for the nav_breadcrumbs helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 47

- (String) options[:nav_brethren_class]=(value)

Default css class for the nav_brethren helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 65

- (String) options[:nav_brethren_index_class]=(value)

Default css class for the nav_brethren_index helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 71

- (String) options[:nav_legitimate_children_class]=(value)

Default css class for the nav_legitimate_children helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 77

- (String) options[:nav_prev_next_class]=(value)

Default css class for the nav_prev_next helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 83

- (String) options[:nav_prev_next_label_next]=(value)

Default “next” label text for the nav_prev_next helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 95

- (String) options[:nav_prev_next_label_prev]=(value)

Default “previous” label text for the nav_prev_next helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 89

- (String) options[:nav_toc_index_class]=(value)

Default css class for the nav_toc_index helper/partial.

Parameters:

  • value (String)

    The class attribute value to use for this item’s containing element.

Returns:

  • (String)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 101

- (Boolean) options[:strip_file_prefixes]=(value)

If true leading numbers used for sorting files will be removed for presentation purposes. This makes it possible to neatly organize your source files in their presentation order on your filesystem but output nice filenames without ugly prefix numbers.

Parameters:

  • value (Boolean)

    true or false to enable or disable this feature.

Returns:

  • (Boolean)

    Returns the current value of this option.



# File 'lib/middleman-pagegroups/extension.rb', line 33

CSS Class Helpers

Returns the value of the the extension option options[:nav_breadcrumbs_alt_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



711
712
713
# File 'lib/middleman-pagegroups/extension.rb', line 711

def nav_breadcrumbs_alt_class
  extensions[:MiddlemanPageGroups].options[:nav_breadcrumbs_alt_class]
end

Returns the value of the the extension option options[:nav_breadcrumbs_alt_label].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



724
725
726
# File 'lib/middleman-pagegroups/extension.rb', line 724

def nav_breadcrumbs_alt_label
  extensions[:MiddlemanPageGroups].options[:nav_breadcrumbs_alt_label]
end

Returns the value of the the extension option options[:nav_breadcrumbs_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



698
699
700
# File 'lib/middleman-pagegroups/extension.rb', line 698

def nav_breadcrumbs_class
  extensions[:MiddlemanPageGroups].options[:nav_breadcrumbs_class]
end

Returns the value of the the extension option options[:nav_brethren_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



737
738
739
# File 'lib/middleman-pagegroups/extension.rb', line 737

def nav_brethren_class
  extensions[:MiddlemanPageGroups].options[:nav_brethren_class]
end

Returns the value of the the extension option options[:nav_brethren_index_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



750
751
752
# File 'lib/middleman-pagegroups/extension.rb', line 750

def nav_brethren_index_class
  extensions[:MiddlemanPageGroups].options[:nav_brethren_index_class]
end

Returns the value of the the extension option options[:nav_legitimate_children_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



763
764
765
# File 'lib/middleman-pagegroups/extension.rb', line 763

def nav_legitimate_children_class
  extensions[:MiddlemanPageGroups].options[:nav_legitimate_children_class]
end

Returns the value of the the extension option options[:nav_prev_next_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



776
777
778
# File 'lib/middleman-pagegroups/extension.rb', line 776

def nav_prev_next_class
  extensions[:MiddlemanPageGroups].options[:nav_prev_next_class]
end

Returns the value of the the extension option options[:nav_prev_next_label_next].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



802
803
804
# File 'lib/middleman-pagegroups/extension.rb', line 802

def nav_prev_next_label_next
  extensions[:MiddlemanPageGroups].options[:nav_prev_next_label_next]
end

Returns the value of the the extension option options[:nav_prev_next_label_prev].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



789
790
791
# File 'lib/middleman-pagegroups/extension.rb', line 789

def nav_prev_next_label_prev
  extensions[:MiddlemanPageGroups].options[:nav_prev_next_label_prev]
end

Returns the value of the the extension option options[:nav_toc_index_class].

Both the built-in helpers and the partials (if you install them) use these helpers in order to access the configuration values. When writing your own partials it is generally unnecessary to use these helpers; you can simply assign your own class name.

The provided helpers and partials use CSS classes, and if the class names collide with your own class names or fail to meet with your naming standards, then they can be changed using the extension options.

Returns:

  • (String)

    Returns the name of the class.



815
816
817
# File 'lib/middleman-pagegroups/extension.rb', line 815

def nav_toc_index_class
  extensions[:MiddlemanPageGroups].options[:nav_breadcrumbs_alt_class]
end

Extended Helpers

- (String) page_classes

Extend the built-in page_classes to include the naked group and page name. The features of this helper are enabled only if options[:extend_page_class] is true.

Returns:

  • (String)

    Returns the classes that correspond to the site hierarchy.



495
496
497
498
499
500
501
# File 'lib/middleman-pagegroups/extension.rb', line 495

def page_classes
  if extensions[:MiddlemanPageGroups].options[:extend_page_class]
    "#{current_page.page_name} #{current_page.page_group} #{super}"
  else
    super
  end
end

Helpers

Generates a breadcrumbs structure as an <ul>. The trailing element is the current page.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

Returns:

  • (String)

    An <ul> containing the breadcrumbs.



521
522
523
524
# File 'lib/middleman-pagegroups/extension.rb', line 521

def nav_breadcrumbs( locals = {} )
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_BREADCRUMBS).render(self, locals)
end

Generates the breadcrumbs structure, alternate form, wherein the trailing element consists of a label indicating “current page,” as an <ul>.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :label (String)

    The text for the label that means “Current page.”

Returns:

  • (String)

    An <ul> containing the breadcrumbs.



540
541
542
543
# File 'lib/middleman-pagegroups/extension.rb', line 540

def nav_breadcrumbs_alt( locals = {} )
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_BREADCRUMBS_ALT).render(self, locals)
end

Generates a fuller list of related topics as a <dl>, with a link to the page as the definition term and the page’s front matter :blurb as the definition definition.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :start (Sitemap::Resource)

    The resource from which to start the list. If not specified, then this resource’s brethren will be listed.

Returns:

  • (String)

    A <dl> containing the list.



560
561
562
563
# File 'lib/middleman-pagegroups/extension.rb', line 560

def nav_brethren( locals = {} )
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_BRETHREN).render(self, locals)
end

Generates a condensed list of related topics as an <ul>, omitting the :blurb front matter data.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :start (Sitemap::Resource)

    The resource from which to start the list. If not specified, then this resource’s brethren will be listed.

Returns:

  • (String)

    An <ul> containing the list.



579
580
581
582
# File 'lib/middleman-pagegroups/extension.rb', line 579

def nav_brethren_index(locals = {})
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_BRETHREN_INDEX).render(self, locals)
end

Generates a fuller list of child topics as a <dl>, with a link to the page as the definition term and the page’s front matter :blurb as the definition definition.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :start (Sitemap::Resource)

    The resource from which to start the list. If not specified, then this resource’s children will be listed.

Returns:

  • (String)

    A <dl> containing the list.



600
601
602
603
# File 'lib/middleman-pagegroups/extension.rb', line 600

def nav_legitimate_children(locals = {})
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_LEGITIMATE_CHILDREN).render(self, locals)
end

Generates a previous and next item as two anchors nested within a <div>. With appropriate CSS this can be rendered as a set of navigation buttons.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :label_previous (String)

    The text for the label that means “Previous page.”

  • :label_next (String)

    The text for the label that means “Next page.”

Returns:

  • (String)

    A <div> containing the links.



621
622
623
624
# File 'lib/middleman-pagegroups/extension.rb', line 621

def nav_prev_next(locals = {})
  locals[:klass] = locals.delete(:class) if locals.key?(:class)
  Haml::Engine.new(MMPartials::MM_PREV_NEXT).render(self, locals)
end

Generate a nested <ul> structure representing the complete table of contents from any particular starting point.

Parameters:

  • locals (Hash) (defaults to: {})

    A hash of key-value pairs that are passed to the structure as local variables.

Options Hash (locals):

  • :klass (String)

    The class attribute value that should be assigned to the containing element.

  • :start (Sitemap::Resource)

    The resource from which to start the list. If not specified, then this resource will be used as the root.

Returns:

  • (String)

    An <ul> containing the list.



641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
# File 'lib/middleman-pagegroups/extension.rb', line 641

def nav_toc_index( locals = {} )
  recurse = locals.key?(:recurse) && locals[:recurse]
  return if recurse && locals[:start].nil?

  commence = locals[:start] || current_page
  pages = commence.legitimate_children

  if recurse
    unless pages.to_a.empty?
      haml_tag :ul do
        pages.each do |p|
          haml_tag :li do
            haml_concat link_to p.data.title, p
            nav_toc_index :start => p, :recurse => true
          end
        end
      end
    end
  else
    capture_haml do
      locals[:klass] = locals.delete(:class) if locals.key?(:class)
      haml_tag :ul, :class => (locals.key?(:klass) && locals[:klass]) || nav_toc_index_class do
        haml_tag :li do
          haml_concat link_to commence.data.title, commence
          nav_toc_index :start => commence, :recurse => true
        end
      end
    end # capture_haml
  end

end

Resource Extensions

- (Array<Sitemap::Resource>) resource.breadcrumbs

Returns an array of resources leading to this resource.

Returns:

  • (Array<Sitemap::Resource>)

    An array of resources.



159
160
161
162
163
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.breadcrumbs
  hierarchy = [] << self
  hierarchy.unshift hierarchy.first.parent while hierarchy.first.parent
  hierarchy
end

- (Array<Sitemap::Resource>) resource.brethren

Returns an array of all of the siblings of this page, taking into account their eligibility for display.

  • is not already the current page.
  • has a sort_order.
  • is not ignored.

The returned array will be sorted by each item’s sort_order.

Returns:

  • (Array<Sitemap::Resource>)

    An array of resources.



159
160
161
162
163
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.brethren
  self.siblings
    .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored && p != self }
    .sort_by { |p| p.sort_order }
end

- (Sitemap::Resource) resource.brethren_next

Returns the next sibling based on order, or nil if there is no next sibling.

Returns:

  • (Sitemap::Resource)

    The resource instance of the next sibling.



159
160
161
162
163
164
165
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.brethren_next
  if self.sort_order == 0
    return nil
  else
    return self.brethren.find { |p| p.sort_order > self.sort_order }
  end
end

- (Sitemap::Resource) resource.brethren_previous

Returns the previous sibling based on order, or nil if there is no previous sibling.

Returns:

  • (Sitemap::Resource)

    The resource instance of the previous sibling.



159
160
161
162
163
164
165
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.brethren_previous
  if self.sort_order == 0
    return nil
  else
    return self.brethren.reverse.find { |p| p.sort_order < self.sort_order }
  end
end

- (Integer) resource.group_count

Returns the quantity of pages in the current page’s group, including this current page, i.e., the number of brethren + 1.

Returns:

  • (Integer)

    The total number of pages in the this page’s current group.



159
160
161
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.group_count
  self.brethren.count + 1
end

- (Array<Sitemap::Resource>) resource.legitimate_children

Returns an array of all of the children of this resource, taking into account their eligibility for display. Each child is legitimate if it:

  • has a sort_order.
  • is not ignored.

The returned array will be sorted by each item’s sort_order.

Returns:

  • (Array<Sitemap::Resource>)

    An array of resources.



159
160
161
162
163
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.legitimate_children
  self.children
    .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored }
    .sort_by { |p| p.sort_order }
end

- (Boolean) resource.navigator_eligible?

Determines whether a page is eligible to include a previous/next page control. This is based on:

  • The group is set to allow navigation via the :navigate front matter key.
  • This page is not excluded from navigation via the use of :navigator => false in its front matter.
  • This page has a sort_order.

Returns:

  • (Boolean)

    Returns true if this pages is eligible for a previous/next page control.



159
160
161
162
163
164
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.navigator_eligible?
  group_navigates = self.parent && self.parent.data['navigate'] == true
  self_navigates = !( self.data.key?('navigator') && self.data['navigator'] == false )

  group_navigates && self_navigates && self.sort_order != 0
end

- (String) resource.page_group

Make page_group available for each resource. Useful for for assigning classes, and/or group conditionals.

Returns:

  • (String)

    The page_group of the current page.



159
160
161
162
163
164
165
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.page_group
  result = File.basename( File.split( self.destination_path )[0] )
  if result == '.'
    result = @app.config[:source]
  end
  result
end

- (String) resource.page_name

Make page_name available for each resource. This is the file’s base name after any renaming has occurred. Useful for assigning classes, etc.

Returns:

  • (String)

    The page_name of the current page.



159
160
161
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.page_name
  File.basename( self.destination_path, '.*' )
end

- (Integer, Nil) resource.page_sequence

Returns the page sequence amongst all of the brethren, and can be used as a page number surrogate. The first page is 1. Pages without a sort order will have a nil page_sequence.

Returns:

  • (Integer, Nil)

    The current page sequence of this resource among its brethren.



159
160
161
162
163
164
165
166
167
168
169
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.page_sequence
  if self.sort_order == 0
    return nil
  else
    self.siblings
      .find_all { |p| p.sort_order && p.sort_order != 0 && !p.ignored }
      .push(self)
      .sort_by { |p| p.sort_order }
      .find_index(self) + 1
  end
end

- (Sitemap::Resource) resource.parent

Return the parent of the resource. This implementation corrects a bug in Middleman as of 4.1.7 wherein Middleman doesn’t return the parent if the the directory has been renamed for output.

Returns:

  • (Sitemap::Resource)

    The resource instance of the resource’s parent.



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.parent
  root = path.sub(/^#{::Regexp.escape(traversal_root)}/, '')
  parts = root.split('/')

  tail = parts.pop
  is_index = (tail == @app.config[:index_file])

  if parts.empty?
    return is_index ? nil : @store.find_resource_by_path(@app.config[:index_file])
  end

  test_expr = parts.join('\\/')
  # eponymous reverse-lookup
  found = @store.resources.find do |candidate|
    candidate.path =~ %r{^#{test_expr}(?:\.[a-zA-Z0-9]+|\/)$}
  end

  if found
    found
  else
    parts.pop if is_index
    @store.find_resource_by_path("#{parts.join('/')}/#{@app.config[:index_file]}")
  end
end

- (Integer) resource.sort_order

Returns the page sort order or 0 if no page sort order was applied.

Pages without a sort order can still be linked to; they simply aren’t brethren or legitimate children, and so don’t participate in any of the automatic navigation features.

Returns:

  • (Integer)

    The current resource’s sort order within its group, or 0 if no sort order was applied.



159
160
161
# File 'lib/middleman-pagegroups/extension.rb', line 159

def resource.sort_order
  options[:sort_order]
end