FAQ

Source files for the Docs

On each page of Assemble's live documentation you will find a "See the templates for this page" link, so you can take a look behind the curtains and get a peek at how we build our own docs. Of course, you can also fork or download the entire project if you want to go deeper with it (or make a pull request, you thoughtful and charitable community member you!).

Generating a list from a collection

The simplest way to generate a list from a collection is to create a block expression using the name of the collection, and the collection items inside.

Collection items from "all pages"

To generate a list of categories for all pages in a target, add the following block expression to a page or a layout (depending on whether or not you want the list to render to a specified page/pages or all pages):

<h2>All Categories</h2>
<ul>
{{#categories}}
  <li>{{category}}</li>
{{/categories}}
</ul>

Now, if two of the pages in our target have categories defined as such:

---
title: Page One
categories:
- apples
- oranges
---

and

---
title: Page Two
categories:
- grapes
- bananas
- coconuts
---

The generated output will be a basic list containing the merged values from the categories collection of each page:

<h2>All Categories</h2>
<ul>
  <li>apples</li>
  <li>bananas</li>
  <li>coconuts</li>
  <li>grapes</li>
  <li>oranges</li>
</ul>

Collection items on a given page

To generate a list of categories for the a page, you would add the following to the page on which you want to generate the list:

{{#page.categories}}
  {{.}}
{{/page.categories}}

Or we can use: {{#each page.categories}}...{{/each}} block expression with the name of the collection as a variable to get the list of pages in the current target

Following the previous example, we'll use the {{#each}}...{{/each}} block expression with the pages variable to get the list of pages in the current target.

Then, using the {{#is}}...{{/is}} comparison helper from the handlebars-helpers library, we can dynamically build navigation items by comparing a property (or properties) from the YAML front matter each page in the list with the given values.

In other words, the is helper will ask: "does this page have a 'getting started' section? If 'true', then add the page as a list item, otherwise skip it". For example, this example shows two different sections being generated:

<h2 > Getting Started</h2 > 
{{#each  pages }} 
  {{#is data.section  "getting started" }} 
    <li >  <a  href ="#" > {{data.title }} </a >  </li > 
  {{/is }} 
{{/each  }} 
<h2 > Configuration</h2 > 
{{#each  pages }} 
  {{#is data.section  "configuration" }} 
    <li >  <a  href ="#" > {{data.title }} </a >  </li > 
  {{/is }} 
{{/each  }}

Any pages with the section: getting-started in the YAML front matter will render in the first list, and pages with section: configuration will render in the second list.

{{#todo}} update the docs once [Pages Arrays][pages-array] can achieve this as well.{{/todo}}

If you want to add class="active" to a navigation item for the "current page", you can achieve this using the {{#is}}...{{/is}} comparison helper from the handlebars-helpers library.

Using YFM properties

You can achieve this using many different variables, but relatively easy one is to compare the basename of the current page to the given value:

<ul class="nav navbar-nav">
  <li{{#is basename "getting-started"}} class="active"{{/is}}>
    <a href="getting-started.html">Getting started</a>
  </li>
  <li{{#is basename "css"}} class="active"{{/is}}>
    <a href="css.html">CSS</a>
  </li>
  <li{{#is basename "components"}} class="active"{{/is}}>
    <a href="components.html">Components</a>
  </li>
  <li{{#is basename "js"}} class="active"{{/is}}>
    <a href="javascript.html">JavaScript</a>
  </li>
  <li{{#is basename "customize"}} class="active"{{/is}}>
    <a href="customize.html">Customize</a>
  </li>
</ul>

The above example is from the navbar in assemble-bootstrap.

Without YFM

However, if you don't use YFM (or don't want to use properties from YFM to create active links), you can compare the destination of the current page to the destination of the linked page to get a truthy or falsy value.

{{#is page.dest this.dest}} class="active"{{/is}}

The trick with using this method is that the context must be correct for it to work. So if you are dynamically generating nav items, as in the [Dynamically build navigation][#dynamically-build-navigation] example, you will need to use ../../ to access the context of pages being generated:

<h2>Getting Started</h2>
{{#each pages}}
  {{#is data.section "getting started"}}
    <li{{#is ../../page.dest this.dest}} class="active"{{/is}}>
      <a href="#">{{data.title}}</a>
    </li>
  {{/is}}
{{/each}}

Generating relative paths for links

To get the relative path from the destination of the current page to the destination of the linked page, the {{relative}} helper works quite well:

{{relative page.dest this.dest}}

As with the previous example, if you nest templates the context must be adjusted for this to work:

<h2>Getting Started</h2>
{{#each pages}}
  {{#is data.section "getting started"}}
    <li{{#is ../../page.dest this.dest}} class="active"{{/is}}>
      <a href="{{relative ../../page.dest this.dest}}">{{data.title}}</a>
    </li>
  {{/is}}
{{/each}}

See the template for this page →

Find an error? Let us know →

Docs / getting started

FAQ