Front Matter

The inclusion of front matter is required for fragment assets and is optional for include and tag-based callback assets.

Front matter must be placed at the very top of the file and it must be surrounded by opening and closing delimiters that are appropriate for the asset's file type.

Trio predefines numerous required and optional front matter properties for you to use in fragment, include and tag-based callback assets.

Below is an example of front matter used in a fragment asset

<!--
template: helloworld
title: Hello, World!
appendToTarget: true
-->
This will be in the excerpt.
<!-- end -->

<h1>Hello, World!</h1>

and below is the JavaScript object that it is converted to.

matter: {
    content: "<h1>Hello, World!</h1>",
    data: {
        template: helloworld
        title: Hello, World!,
        appendToTarget: true
    },
    isEmpty: false,
    excerpt: "This will be in the excerpt."
}

Excerpts are only supported in fragment assets.

Appropriate Delimiters By Asset Type

Fragment and include assets use opening and closing HTML comment tags "<!--", "-->" as their front matter delimiters.

Tag-Based callbacks use opening and closing JavaScript block comment tags "/*", "*/" as their front matter delimiters.

Predefined Front Matter Properties For All Fragments

template

• required, type string
• Names the template (as of v2, the .html file extension isn't required) that the fragment is associated with.

title

Prior to v4.3.0, title was required and had no default value.

• optional, type string, default value Document
• Sets the title tag of the page.

appendToTarget

• optional, type boolean, default value false
• If true Trio appends the fragment's content to the tag in the template that is decorated with the data-trio-fragment attribute.
• If false Trio replaces the tag in the template that is decorated with the data-trio-fragment attribute with the fragment's content. Beginning with v3.1.0, if building for development, Trio will also preserve the target tag in the generated markup as a comment.
• See data-trio-fragment for more information.

collection

Introduced in v2.0.0.

Fragments that include the collections property in their front matter are always treated as if they are stale and therefore they never need to include the alwaysBuild property.

• optional, type hash, default value none
• See Collections for more information.

collection
.filterFn

• required, type string, default value none
• Names the JavaScript module in the source/filters folder that Trio calls to return the data it will use to create the pages in the collection.
• See Collections for more information.

alwaysBuild

• optional, type boolean, default value false
• If true then Trio will always treat this fragment as if it is stale when building your project incrementally.
• This should be used when generating composites that consume the metadata generated from assets that are unrelated to this composite, such as when generating pages that contain lists of other pages (e.g. blog pages, tag pages, category pages, catalog pages, portfolio pages, etc.).
• See Declaring External Dependencies To Trigger Incremental Builds for details.

permalink

Introduced in v3.0.0

• optional, type string, default value none
• Permalinks defined in fragment front matter only affect the destination paths and ultimately the URLs that are generated for those particular fragments.
• The destination paths of permalinks defined in fragment front matter are interpreted as being relative to the root/public (or root/release, if generating a release build) folder.
• All fragments generated for collections which define permalinks share the same permalink.
• To define a permalink in a fragment's front matter, you include the permalink front matter property and assign it the destination path that Trio will use when it generates the destination path for the fragment.
• See Defining A Permalink In Fragment Front Matter for more information.

custom properties

• supported, type any supported front matter data type

Predefined Front Matter Properties Specific To Article Page Fragments

tag

• optional, type string | array, default value none
• Can be used to assign one or more tags to a blog article.

category

• optional, type string | array, default value none
• Can be used to assign one or more categories to a blog article.

Predefined Front Matter Properties Specific To Includes

appendToTarget

• optional, type boolean, default value false
• If true Trio appends the include's content to the tag in the fragment or template that is decorated with the data-trio-include attribute that names the include.
• If false Trio replaces the tag in the fragment or template that is decorated with the data-trio-include attribute that names the include with the include's content. Beginning with v3.1.0, if building for development, Trio will also preserve the target tag in the generated markup as a comment.

custom properties

• not supported

Predefined Front Matter Properties Specific To Tag-Based Callbacks

dataDependencies

• optional, type string | array, default value none
• Used to declare one or more JSON data file dependencies.
• See Declaring Internal Dependencies To Trigger Incremental Builds for details.

moduleDependencies

• optional, type string | array, default value none
• Used to declare one or more Node module dependencies.
• See Declaring Internal Dependencies To Trigger Incremental Builds for details.

custom properties

• not supported

See Also

• Blogging
• Collections
• Fragment
• Include
• Incremental Build
• Core Concepts
• Metadata
• Permalinks
• Tag-Based Callbacks