Core Concepts

Understanding the core concepts presented on this page will enable you to use Trio to its fullest potential.

Project Assets

Creating web pages with Trio involves the use of project assets to create and augment composites which Trio eventually saves to your computer's file system as HTML files. The following project assets are available to you to compose your pages:

It helps to think of composites as pages that haven't been written to the file system yet, that only exist in your computer's memory.

Fragments

Fragments are either .html or .md file types that you create in the root/source/fragments folder. Fragments must always include front matter at the very top of the file and optionally can have their own content.

Fragment front matter must include the template property to which is assigned the name of the template that the fragment is associated with.

A fragment asset can only be associated with a single template asset.

Templates

Templates are .html file types that you create in the root/source/templates folder. Templates define the overall layout of your site's pages (i.e. they include the !DOCTYPE document preamble, html, head and body sections typically found in an HTML document).

Templates never include front matter.

A template asset can be associated with multiple fragment assets.

Includes

Includes are either .html or .md file types that you create in the root/source/includes folder. They are used to add reusable blocks of content to the composites created from fragment and template assets and can be used across multiple pages (e.g. headers, footers, indexes, etc.). They can optionally include front matter at the very top of the file.

You can add as many include assets as needed into both template and fragment assets by decorating the tags you are targeting with the data-trio-include="name + file type" of the include file or data-trio-include="the name of a property declared in the fragment's front matter" whose value is the name of the include file.

JSON Data Files

JSON data files are .json file types that you create in the root/source/data folder. Tag-based callbacks can access these files' data through the metadata that is passed to them.

You can hand-code these data files yourself or you can create NPM tasks that, for example, retrieve the data from a local database, a content management system, or a remote service.

Metadata

Metadata is the collection of data that Trio derives from your project's other assets and from the root/trio.json configuration file and uses the metadata internally to build your site.

Trio also passes metadata to the tag-based callbacks it finds declared in your project's fragment, template and include assets, which they can use to further augment your composites. Trio organizes its metadata in a structured format that makes using it in your tag-based callbacks easier to reason about.

For example, you can use this metadata in your tag-based callbacks to:

• Create links to other pages on your web site.
• Generate content based on JSON data or from custom front matter properties.
• Make lists of blog articles related by their categories and tags.
• Construct links to the next and previous blog article based on their published dates.

After each development build of your project, Trio persists most of the metadata that it collects to a file named root/trio.manifest.json. You can use this file as a reference to assist you when you are coding your collection filter functions and tag-based callbacks.

Tag-Based callbacks

Tag-based JavaScript Callbacks are JavaScript Node modules that you define in the root/source/callbacks folder that Trio calls to augment your composites with dynamic content residing in the metadata (see above) that is passed to them. Each module must export a single function which takes a single argument. See Advanced Page Composition below for more information.

A Page Composition Overview

Anatomy Of A Generated Page

Trio's approach to page generation (also called page composition throughout these document pages) is quite different from other static site generators and it is what makes Trio the flexible and powerful tool that it is.

1. First and foremost, every web page (.html file) that is generated must have a template asset and a fragment asset (see project assets above). Trio uses the markup from the template asset identified by the template property in the fragment's front matter (see front matter below) to initialize a brand new composite.
2. Trio then searches the newly created composite's content for a single tag that has the "data-trio-fragment" attribute (see tag attributes below). If one is found, Trio will copy any content that the fragment may have to that tag. If the fragment's content is in markdown format, Trio will convert the markdown to markup prior to copying.
3. Trio then searches the composite for all the tags that have "data-trio-include" attributes (see tag attributes below), which name the include files (see project assets above) whose content is copied to their respective tags in the composite. If an include file's content is in markdown format, Trio will convert the markdown to markup prior to copying.
4. Trio then searches the composite for all the tags that have "data-trio-callback" attributes (see tag attributes below), which name the Node modules that Trio calls to dynamically add content derived from Trio's metadata to the composite (see advanced page composition below).
5. Finally, page composition is complete and Trio writes the composite to an .html file using Trio's file naming conventions (see page generation).

Trio repeats this process for every fragment/template pair declared in the project.

Anatomy Of A Generated Page, Steps 1 - 3: Basic Page Composition

At a minimum, every page that Trio generates is composed of a single fragment asset and a single template asset and optionally one or more include assets.

Basic page composition allows template assets to provide the overall layout of pages, fragment assets to augments those pages with their own unique content, and include assets to add blocks of commonly repeated content.

Basic page composition produces pages that don't vary much in the way of content other than what each fragment, template and include asset contributes. Often you will find that your pages require dynamic content, which is what advanced page composition provides through the use of tag-based callbacks and metadata.

Perhaps what distinguishes basic page composition the most is that, unlike advanced page composition (see below), it doesn't require the use of tag-based callbacks and JavaScript Node modules.

Anatomy Of A Generated Page, Step 4: Advanced Page Composition

Trio doesn't use a framework (e.g. React, etc.) or a templating engine (e.g. Handlebars, Liquid Templates, etc.) to augment your composites with dynamic content. Instead, Trio uses JavaScript Node modules to augment your composites with dynamic content through its tag-based callback mechanism, which is kind of awesome if you think about it.

Since Trio is built on top of Node (it is currently using v14 LTS), you have all the latest ES6+ goodies to work with without having to transpile your code. In addition, and this is a biggie, your markup remains "clean", readable, easy to reason about and maintain because it isn't littered with scattered bits of framework API calls or with templating engine statements.

You can add as many tag-based callback assets as needed to a template, fragment and include assets by decorating the tags you are targeting with the data-trio-callback="name of module" tag attribute.

Tag Attributes

Tag attributes that start with data-trio-* are markers that indicate to Trio that it should take certain actions when it encounters them, such as, for example, targeting a tag with an include asset's content (e.g. data-trio-include) or with a fragment asset's content (e.g. data-trio-fragment) or calling a JavaScript Node module (e.g. data-trio-callback) to augment a composite with dynamic content.

Front Matter

YAML is a human readable data serialization language (don't let that intimidate you -- it is actually very simple to use) that you use to add configuration data to your project's fragment, include and tag-based JavaScript callback assets. Because it's required to be added to the very top of a file, it can also just be called "front matter", which is a convention that you will often see used throughout Trio's documentation.

Trio predefines numerous front matter properties that it expects to find in your assets, which it uses internally when creating its composites. For example, Trio expects to find the name of the template that a fragment is associated with in its front matter template property.

You can also define your own custom front matter properties in fragment assets as need requires. Both Trio's predefined front matter properties and any custom front matter properties that you define are exposed to your tag-based callbacks.

Trio uses the awesome OS library called gray-matter to implement its front matter support.

Collections

Introduced in Trio v2.0.0, Collections are groups of pages that are dynamically generated by Trio that you would otherwise have to manually create yourself.

Permalinks

Introduced in Trio v3.0.0, Permalinks are used to modify how Trio generates the destination paths and ultimately the URLs of pages that it generates for your site.

Summary

Trio's use of common metaphors for its project assets, its approach to page composition, its organized collections of metadata and its tag-based callback mechanism serve to create an easy to learn and use, highly adaptable and powerful platform upon which to create your static sites.

See Also

• Collections
• Fragment
• Front Matter
• Include
• JSON Data
• Metadata
• Permalinks
• Tag Attributes
• Tag-Based Callbacks
• Template