YAML front matter

YFM is an optional section of valid YAML that is placed at the top of a page and is used for maintaining metadata for the page and its contents.

YFM can be used with both pages and partials, so unless otherwise noted you can safely assume that when the documentation refers to the YFM of a page, the same also applies to the YFM of a partial.

Example

---
title: YAML Front Matter
description: A very simple way to add structured data to a page.
---
<h1> {{ title }} </h1>
<p> {{ description }} </p>
Page content here...

YFM "Variables"

Built-in Variables

layout : Optionally define or override the layout to use. You must include file extension, since Assemble can process multiple file types. Layout files can exist in any directory, and may be.
published : set to false to exclude a file from being rendered by a task-target.
category/categories/tags : Define the categories and tags as YAML lists or a space-separated string. for each category and tag, Assemble will generate a page in the dest directory.

If set, allows to specify tags attributed to given entry. Tag pages are generated automatically. Entry may belong to more than one tag, use YAML List to specify multiple tags.

Custom Variables

Any variables in the front-matter that are not predefined are mixed into the data that is sent to the Liquid templating engine during the conversion. For instance, if you set a title, you can use that in your layout to set the page title:

<title>{{ page.title }}</title>

Using Lo-Dash templates in YFM

Metadata "conduit"

This may not be obvious at first, is that YAML Front-Matter acts as a kind of "conduit" for passing information to pages via Lo-Dash templates.

So you could do this:

grunt.initConfig({
  assemble: {
    component: {
      options: {
        data: 'page.json' 
      },
      files: {
        'index.html': ['src/pages/*.hbs' ]
      }
    }
  }
});

With page.json containing:

{
  "index ": {
    "title ": "Home" 
   },
  "about ": {
    "title ": "About Us" 
   }
 }

And in the YFM of the page, use underscore templates:

---
title: <%= page.index.title %>
---
{{ title }}

Alternatively, inside the Grunfile you can use grunt.config.set to define the data to be used for a given variable:

grunt.config.set('page.index.title', 'Home' );

Example usage

---
title:
list: <% _.forEach(people, function(name) { %><li><%= name %></li><% }); %>
people:
- Jon Schlinkert
- Brian Woodward
---
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
  </head>
  <body>
    <section class="people">
      <ul>
        {{{list}}}
      </ul>
    </section>
  </body>
</html>

---
layout: default.hbs
title: Early humans discovered...
description: Lots of things, because they were early humans.
date: 2013-07-04
categories:
- anthropology
- unibrows
- various wooly animals
tags:
- rocks
- wheel
- 30 inch wooden rims
published: false
---

---
title: My Blog
description: Like I said, my bloggg!
example:
  custom:
    variables:
    - one
    - two
    - three
---
<div class="page-header">
  <h1>{{title}}</h1>
  <p class="lead">{{description}}</p>
</div>
<ul>
  {{#each example.custom.variables}}
  <li>{{.}}</li>
  {{/each}}
</ul>