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

## Configuration Reference

Below is the complete configuration reference.

<%= partial 'partials/yard_config' %>