Extract YAML data from specially-formatted comments at the top of your Craft project twig templates
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
tests
.gitignore
.scrutinizer.yml
CHANGELOG.md
LICENSE.md
README.md
codeception.yml
composer.json
composer.lock

README.md

Front Matter for Craft CMS 3.x

Build Status Scrutinizer Code Quality Code Coverage License

Front Matter allows you to extract YAML data from specially-formatted comments at the top of your twig templates. This is especially useful for including a pattern library inside your Craft CMS project.

Requirements

This plugin requires Craft CMS 3.0.0 or later.

Installation

To install the plugin, follow these instructions.

  1. Open your terminal and go to your Craft project:

    cd /path/to/project

  2. Then tell Composer to load the plugin:

    composer require tinydots/craft-front-matter

  3. In the Control Panel, go to Settings -> Plugins and click the “Install” button for Front Matter.

Usage

Defining data

You can add YAML metadata to the top of any twig template by surrounding it in {#--- and ---#} tags. Because the YAML data is inside a twig comment, you can still {% include %} and {% embed %} templates as normal, with or without the plugin installed.

Given a _components/link.html template for rendering a link, with the following YAML front matter data:

{#---
title: Link
description: >
    This is a tiny component for rendering a single link.

        {% include "_components/link" with {
            url: 'https://www.google.com',
            text: 'Google',
        } %}
variables:
    text: The text to use as the body of the link
    url: The url of the target
examples:
    - text: Craft CMS
      url: https://www.craftcms.com
    - text: Google
      url: https://www.google.com
---#}

<a href="{{ url }}">{{ text }}</a>

Accessing data

You can access the YAML data as an array from other templates with craft.frontMatter.parse(template):

{% set component = craft.frontMatter.parse("_components/link") %}

<h2>{{ component.title }}</h2>

{{ component.description|markdown }}

Pattern Libraries

The main use-case for embedding YAML data in templates is for creating a style guide or pattern library inside the Craft project itself.

Collections/arrays are available to use as normal so can be used to document the variables the template accepts:

{% if component.variables is defined %}
    <h3>Variables</h3>
    <dl>
        {% for variable, description in component.variables %}
            <dt><code>{{ variable }}</code></dt>
            <dd>{{ description|markdown }}</dd>
        {% endfor %}
    </dl>
{% endif %}

You can output the escaped source of the template without the YAML data, using craft.frontMatter.source(template):

<h3>Source code</h3>

<pre>
    {{- craft.frontMatter.source("_components/link") -}}
</pre>

If you use simple strings and arrays as input variables in your template, you can even embed a few examples of the output by passing them back in to a normal {% include %} of the template:

{% if component.examples is defined %}
    <h3>Examples</h3>

    {% for example in component.examples %}

        {# Output the rendered template with the example data #}
        {% include "_components/link" with example only %}

        {# Output the escaped rendered HTML output#}
        <pre>{% filter escape('html') %}{% include "_components/link" with example only %}{% endfilter %}</pre>

    {% endfor %}
{% endif %}