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

This extension extends **Middleman** built-in helpers in order to offer more
features.

<%= partial 'partials/yard_helpers_extended' %>

The current value of `page_classes` is "`<%= page_classes %>`".

* * *

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

<%= 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
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 `: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
`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}

<%= partial 'partials/yard_helpers' %>

* * *

## Output Helpers’ Examples

The examples below illustrate the output of each of the output helpers as they
are generated on this very page.

<dl class="examples_list">
  <dt>nav_breadcrumbs</dt>
  <dd markdown="1">
~~~ html
<%= nav_breadcrumbs %>
~~~
  </dd>

  <dt>nav_breadcrumbs_alt</dt>
  <dd markdown="1">
~~~ html
<%= nav_breadcrumbs_alt %>
~~~
  </dd>

  <dt>nav_brethren</dt>
  <dd markdown="1">
~~~ html
<%= nav_brethren %>
~~~
  </dd>

  <dt>nav_brethren_index</dt>
  <dd markdown="1">
~~~ html
<%= nav_brethren_index %>
~~~
  </dd>

  <dt>nav_legitimate_children</dt>
  <dd markdown="1">
~~~ 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}
  </dd>


  <dt>nav_prev_next</dt>
  <dd markdown="1">
~~~ html
<%= nav_prev_next %>
~~~
  </dd>


  <dt>nav_toc_index</dt>
  <dd markdown="1">
~~~ html
<%= nav_toc_index :start => current_page.breadcrumbs.first %>
~~~
  </dd>
</dl>