nav

Display site navigations.

{{ nav }}

Displays a list of folders and pages. Recently updated in v1.7 to traverse deeper through recursion.

Simple Example

<ul class="nav">
  {{ nav from="/" max_depth="2" }}
  <li>
    <a href="{{ url }}" {{ if is_current }} class="current"{{ endif }}>
        {{ title }}
    </a>
  </li>
  {{ /nav }}
</ul>

Parameters

from

The folder from which to start building your nav.

Default: the current folder based on your URL.

{{ nav from="/" }}

exclude

A pipe-separated list of folders to exclude

{{ nav from="/" exclude="site-map|chamber-of-secrets" }}

max_depth

Maximum number of subdirectory levels to traverse, letting you build a multi-level nav.

Default: 1

{{ nav from="/" max_depth="2" }}

include_entries

You can include entries in your nav by setting to true. Somewhat of an edge case, but it makes the Nav tag capable of fetching just about any and all of your content.

Default: false

{{ nav from="case-studies" include_entries="true" }}

folders_only

Only include page.md files when fetching content. This is the default behavior as it generally lets you build a nav of your content sections and respective parent/landing pages.

Default: true

{{ nav from="/" folders_only="false" }}

include_content

Whether to include all content fields when fetching pages/entries.

Default: true (Since 1.10)

{{ nav from="/" include_content="false" }}

limit

If set, limits the the maximum number of pages to display.

{{ nav from="/" limit="4" }}

offset

If set, skips over the specified number of pages.

{{ nav from="/" offset="4" }}

Tag Variables

The following variables are available within the nav tag:

• is_current — a boolean as to whether the item in the current iteration of the loop matches the URL being viewed
• is_parent — a boolean as to whether the item in the current iteration of the loop is a parent of the URL being viewed
• url — the URL to this folder
• title — the name of this folder, as pulled from the page file within it
• children — if there are subdirectories found, a list of subdirectories within this folder
• parent (added in v1.7.5) — a tag pair that gives you access to information about the parent page for the current child content being looped through, within this tag pair you can always use {{ url }} and {{ title }}, and if your nav tag set include_content to true, you can also use any other variable for that content

Recursion (added in 1.7)

It’s also now possible to use recursive tags for semi-automatically creating deeply-nested lists of links as your navigations. A sample set-up looks something like this:

<ul>
   {{ nav from="/{segment_1}" max_depth="4" folders_only="false" }}
      <li>
         <a href="{{ url }}"{{ if is_current || is_parent }} class="on"{{ endif }}>{{ title|smartypants|widont }}</a>
         {{ if is_current || is_parent }}
            {{ if children }}
               <ul>{{ *recursive children* }}</ul>
            {{ endif }}
         {{ endif }}
      </li>
   {{ /nav }}
</ul>

This example is from the Acadia theme’s sub-navigation partial. The {{ *recursive children* }} tag will repeat the contents of the entire {{ nav }} tag using child elements if they exist. This means that as long as there are children to display, and we’re still on either the current or parent page of those children, the nav tag will traverse deeper.

It’s an admittedly weird concept, and might take some fiddling with to truly understand, but is very powerful when fully understood. Take the time. Learn to wield it. A powerful jedi will you be.

{{ nav:breadcrumbs }}

Displays a list of breadcrumbs that lead to a given page.

Sample Usage

<nav class="breadcrumbs">
    <ul>
        <li><a href="/">Home</a></li>
        {{ nav:breadcrumbs include_home="no" }}
            {{ if is_current }}
                <li>{{ title }}</li>
            {{ else }}
                <li><a href="{{ url }}">{{ title }}</a></li>
            {{ endif }}
        {{ /nav:breadcrumbs }}
    </ul>
</nav>

Parameters

Parameter	Description
url	URL to target with the breadcrumbs, the current URL by default
include_home	a boolean as to whether the breadcrumb list should include the homepage or not, true by default
reverse	a boolean as to whether the breadcrumb order should be reversed, in order of the target url back towards the homepage, false by default
backspace	the number of characters to remove from the last breadcrumb listing, 0 by default
trim	a boolean as to whether to trim whitespace between the tags, true by default

{{ nav:exists }}

Let’s you test the results of a set of nav tag parameters before displaying any content.

Example

{{ nav:exists from="/{segment_1}" max_depth="4" folders_only="false" }}
   <ul>
      {{ nav from="/{segment_1}" max_depth="4" folders_only="false" }}
         <li>
            <a href="{{ url }}"{{ if is_current || is_parent }} class="on"{{ endif }}>{{ title|smartypants|widont }}</a>
            {{ if is_current || is_parent }}
               {{ if children }}
                  <ul>{{ *recursive children* }}</ul>
               {{ endif }}
            {{ endif }}
         </li>
      {{ /nav }}
   </ul>
{{ /nav:exists }}

The unordered-list will only be displayed if the parameters in {{ nav:exist }} find content to display. Note that these tags use blink data, which means checking for existing navigation content and then displaying that content is not a performance hit.

Parameters

from

The folder from which to start building your nav.

Default: the current folder based on your URL.

{{ nav from="/" }}

exclude

A pipe-separated list of folders to exclude

{{ nav from="/" exclude="site-map|chamber-of-secrets" }}

max_depth

Maximum number of subdirectory levels to traverse, letting you build a multi-level nav.

Default: 1

{{ nav from="/" max_depth="2" }}

include_entries

You can include entries in your nav by setting to true. Somewhat of an edge case, but it makes the Nav tag capable of fetching just about any and all of your content.

Default: false

{{ nav from="case-studies" include_entries="true" }}

folders_only

Only include page.md files when fetching content. This is the default behavior as it generally lets you build a nav of your content sections and respective parent/landing pages.

Default: true

{{ nav from="/" folders_only="false" }}

include_content

Whether to include all content fields when fetching pages/entries.

Default: false

{{ nav from="/" include_content="true" }}

{{ nav:count }}

Counts the number of items in the navigation.

Sample Usage

{{ nav:count }}

Parameters

from

The folder from which to start building your nav.

Default: the current folder based on your URL.

{{ nav:count from="/" }}

exclude

A pipe-separated list of folders to exclude

{{ nav:count from="/" exclude="site-map|chamber-of-secrets" }}

max_depth

Maximum number of subdirectory levels to traverse, letting you build a multi-level nav.

Default: 1

{{ nav:count from="/" max_depth="2" }}

include_entries

You can include entries in your nav by setting to true. Somewhat of an edge case, but it makes the Nav tag capable of fetching just about any and all of your content.

Default: false

{{ nav:count from="case-studies" include_entries="true" }}

folders_only

Only include page.md files when fetching content. This is the default behavior as it generally lets you build a nav of your content sections and respective parent/landing pages.

Default: true

{{ nav:count from="/" folders_only="false" }}

include_content

Whether to include all content fields when fetching pages/entries.

Default: false

{{ nav:count from="/" include_content="true" }}