Tweet

Docs /  data

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>

YAML Front-Matter in Partials

---
title: <%= component.name || pkg.name %>
---
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>{{ titleize title }} Component</title>
    <link rel="stylesheet" href="{{assets}}/css/{{title}}.css">
  </head>
  <body>
    <div class="container">
      <!-- {{title}} -->
      <div class="row">
        <div class="span3">
          <div class="dropdown">
            <div>User Settings</div>
            <ul class="dropdown-menu">
              <li><a href="#">My Profile</a></li>
              <li><a href="#">Friend Requests</a></li>
              <li><a href="#">Account Settings</a></li>
              <li><a href="#">Support</a></li>
              <li><a href="#">Log Out</a></li>
            </ul>
          </div>
        </div>
      </div><!-- /{{title}} -->
      {{> body }}
    </div>
    <script src="{{assets}}/js/{{title}}.js"></script>
  </body>
</html>

Rendering Lists

Use YAML Associative Arrays for rendering lists of information.

Indented Blocks, common in YAML data files, use indentation and new lines to separate the key: value pairs

---
title: Associative arrays
people:
  name: John Smith
  age: 33
morePeople: {name: Grace Jones, age: 21}
---

Inline Blocks such as morePeople, common in YAML data streams, use comma+space to separate the key: value pairs between braces:

Used in templates like this:

<div class="page-header">
  <h1>{{{title}}}</h1>
</div>
<div class="examples">
  <h4>Associative arrays</h4>
  <dl class="dl-horizontal">
    {{#people}}
      <dt>Name:</dt> <dd>{{name}}</dd>
      <dt>Age:</dt>  <dd>{{age}}</dd>
    {{/people}}
    {{#morePeople}}
      <dt>Name:</dt> <dd>{{name}}</dd>
      <dt>Age:</dt>  <dd>{{age}}</dd>
    {{/morePeople}}
  </dl>
</div>

More examples

See some great usage examples in assemble's YAML test files:

  • YAML associative arrays
  • YAML block literals
  • YAML comments
  • YAML data files
  • YAML data types
  • YAML documents
  • YAML lists
  • YAML relational-trees
  • YAML variables

FAQ

  • With Assemble you may do just about anything with YAML front matter that you can do with valid YAML
  • YFM must be valid YAML
  • YFM cannot be parsed if it is not the first thing on the page
  • Assemble parses YAML front matter into an object literal.
  • YFM allows you to define variables for a page, directly inside the page.

Custom Variables

  • You may use any of the default variables provided by Assemble, or you may define your own custom variables inside the YFM of a file.
  • You may add as many custom variables as you require

Lo-Dash Templates

  • You may use underscore Lo-Dash templates in YFM
  • Assemble exposes all variables defined in YAML front-matter to the page in which they were defined, thus...
  • Using Lo-Dash templates in YFM enables programmatic access to those pages across your project.
  • YFM may be used in any file that Assemble processes through any of the src-dest or files mappings formats available in Grunt.js.
  • YFM is best used for structured data, like configuration settings or metadata for a page, as opposed to long-form content.
  • YFM offers an easy way to maintain metadata or rendered data for pages and partials, as an optional  alternative to using "external" .json or .yaml data files
  • YFM isn't the best option for long-form content or extensive amounts of metadata. In these cases you might want to consider externalizing your data to JSON or YAML files instead.

See the template for this page →

Find an error? Let us know →