options.collections

Default Collections

The following built-in collections are available at the root of the context:

Collection	Collection item	Description
tags	tag	Used to specify tags associated with the current page. Multiple tags may be associated with each page. Useful for adding semantic tags or tag clouds to your content.
categories	category	Used to specify categories associated with the current page. Multiple categories may be associated with each page. Similar to tags but more appropriate for categorizing pages by "broader" concepts.
pages	page	See Pages collection differences below

Pages collection differences

" Pages " and "page" differ from other collections and collection items in the following ways:

• Any files specified in the src of a given target will be the collection items associated with the "pages" object for that target.
• Although a "page" is a collection item, there is currently no concept of "pages with related pages". In other words there is no object which contains a collection of pages associated with a given page.

Collection items

You may then add items to collections in the YAML front matter of any files that should include those collections:

---
title: My Blog
widgets:
- one
- two
- three
---

Collections Options

Implemented

• name:: the name of the collection, plural form
• inflection: the name of an individual collection item, in singular form
• sortorder: direction in which to sort the collection. Accepted values are (case insensitive): asc|ascending, desc|descending.
• sortby: you may sort the collection by any field available in the page's data context

Planned

• index: the template to use for generating an index page for the collection, such as: src/templates/indices/archives.hbs.

options: {
  collections: [
    {
      // Collection options 
      name: 'items',
      inflection: 'nav-item'  // singular form 
    },
    {
      name: 'archives',
      inflection: 'post'  ,
      sortorder: 'ascending', // or any of the following ['asc', 'desc', 'descending'] upper or lower case 
      sortby: 'datetime',
      index: 'src/templates/indices/archives.hbs' 
    }
  ]
}

List of associate pages

Additionally, any collection item from the collections object can list the pages associated with that collection. For example, each "tag" would list the pages associated with that tag.

{
  tag: 'news',
  pages: ['one.html', 'two.html', 'three.html' ]
}

Custom collections

options.collections

type: Array default: null

Custom collections may be defined using the collections option:

assemble: {
  options: {
    collections: ['widgets', 'posts' ]
  }
}

And then in the YAML front matter of a page:

---
widgets:
- one
- two
- three
---

There are no restrictions on the number of collections created, you may specify as many custom collections as you require.

Automatic inflection

Currently, for the sake of ease of use, the collection method uses the inflection library to convert a collection's item key into the correct syntax:

• tags converts to: { tag: 'ficus', pages: [] }
• categories converts to: { category: 'trees', pages: [] }

If words you wish to use are either missing or don't work properly, please let us know by creating an Issue on Assemble's GitHub repository.

Usage examples

Declaring tags and categories for a page within the page's YAML front matter

---
tags:
- feature
- priority
categories:
- open
---

List all tags

<ul > 
  {{#tags }} 
  <li > <a  href ="/tag/{{tag }}.html" > {{tag }} </a > </li > 
  {{/tags }} 
</ul > 

List all categories

<ul > 
  {{#categories }} 
  <li > <a  href ="/category/{{category }}.html" > {{category }} </a > </li > 
  {{/categories }} 
</ul > 

List tags on current page

<ul > 
  {{#page.tags }} 
  <li > {{. }} </li > 
  {{/page.tags }} 
</ul > 

List categories on current page

<ul > 
  {{#page.categories }} 
  <li > {{. }} </li > 
  {{/page.categories }} 
</ul > 

---

See the template for this page →