---
title:  Groups
blurb:  Groups are the fundamental organizational technique that enable
        automatic page management, navigation, and tables of contents simple to
        implement, and they help you stay organized.
layout: template-logo-medium
---
<%= md_links %>
<%= md_images %>


<%= current_page.data.title %>
==============================

<%= current_page.data.blurb %>

What are groups?
----------------

A Group is one of more files in a single level of directory, and also any
`index.html` file of immediate subdirectories of the group.

Group directories require one file that will compile into `index.html` file in
that directory, e.g., `index.html.md.erb`. This file _is not part of the group_;
it serves as the _parent_ to the group. The files in the group are all 
_children_ of the `index.html` file. Each file in the group is a _sibling_ of
the other files in the group.

Groups are named based on their containing directory. The highest level group is
`Base.lproj` and cannot be changed. Group names are generally not user-facing,
and the Apple Help system requires this directory name, so don’t worry about it.

Example:

~~~
Base.lproj/
  index.html
  introduction.html
  basics/
    index.html
    counters.html
~~~

The `Base.lproj` consists of two pages: `introduction.html`, and
`basics/index.html`. The highest-level `index.html` is the parent of this
group.

Groups can be nested to arbitrary levals.


Page order in groups
--------------------

Using the included [helpers][helpers], you can designate tables of contents,
related pages, indices, etc., for groups with a single line of code. In addition
_Middlemac_ includes built-in navigation widgets for groups, should you like to
use them.

A group member’s sort/navigation order is determined two ways.

- Files in the group can have an `:order` key in the frontmatter, or
- File names can be prefixed with an integer sort order followed by an
  underscore, .e.g, `40_hello.html.md.erb` or `12345_big_numbers.html.md.erb`.

Some important aspects about order numbers in groups are:

- If both a prefix and `:order` key are present, then the `:order` key takes
  precedence.
- If any pages in the same group end up with the same sort order, then the
  actual behavior is undefined.
- Parent `index.html` files cannot be prefixed, and so must include an `:order`
  key in their frontmatter, or prefix the containing directory name instead.
- Pages without a sort order are _not_ present in any of the automatic 
  navigation or contents partials or helpers. This is by design. You can still
  link to them, though.
- Prefixing file names can be convenient so that source files are sorted in your
  file system the same way they will be displayed in your help system. Keep in
  mind, though, that if you’re using the automatic markdown links from the
  `md_links` helper and name collisions occur, then it’s possible that some of your
  links will become invalid.
- Finally, page orders do not have to be sequential. It may be helpful to space
  them apart so that later insertions can be simplified.