Template

Template System

Overview

When generating pages with PureBuilder Simply, a template is required.

The actual format of the template used depends on the selected document processor.
In most cases, templates using eRuby are employed.

By leveraging the template system, you can incorporate dynamic elements at generation time.

Specifying Template Files

A template file can be specified as the value of template in the configuration file.

The type of template specified here depends on the document processor.

If omitted, template.html (for Pandoc) or template.erb (for systems using eRuby templates) in the document source root will be used.

Parameters in eRuby Templates

The following variables are available within eRuby templates:

In most cases, you will use frontmatter and article_body.

Rarely, the following instance variables are also available:

From the perspective of templates, @indexes is likely incomplete, since it only becomes complete after all documents have been generated.

These instance variables were largely provided for the now-deprecated plugins feature, and their use in templates is not recommended.
Accessing them from eRuby templates is already deprecated.

Template Features in Pandoc

When using Pandoc as the document processor, Pandoc’s template functionality is employed.

Within Pandoc, variable expansion using values from the frontmatter is possible.
PureBuilder Simply automatically sets additional values into the frontmatter, and intervention via Blessing is also possible, making active use of Pandoc’s template features.

For details on Pandoc’s template functionality, see Pandoc User’s Guide #Templates.

Frontmatter

Frontmatter in PureBuilder Simply

In the context of document processors, “Frontmatter” almost always refers to “YAML Frontmatter,” a block of YAML metadata placed at the beginning of a Markdown document.
However, PureBuilder Simply does not limit itself to YAML Frontmatter; it uses the term “Frontmatter” to refer to integrated, document-level metadata in general.

Location of Metadata

Markdown YAML Frontmatter

In Markdown, you can place YAML metadata at the beginning of a document.
This is called YAML Frontmatter.

---
title: This is first document
date: 2020-07-14
author: Harukamy
---

YAML Frontmatter is not part of the core Markdown specification, but many Markdown processors support it.

In PureBuilder Simply, for Markdown files, YAML Frontmatter is always supported regardless of whether the document processor itself supports it or not.

reStructuredText docinfo

In reStructuredText, if the first non-comment element in a document is a field list, it is treated as metadata called docinfo.

  :title: This is first document
  :date: 2020-07-14
  :author: Harukamy

PureBuilder Simply recognizes this and treats it as frontmatter.
Therefore, even if a reStructuredText processor that does not understand docinfo is added, it can still be handled as frontmatter.

However, since few users currently use reStructuredText with PureBuilder Simply, it is unclear whether the current functionality is sufficient.
If you encounter issues, please report them via a GitHub issue.

Meta Files

If a file named .meta.${filename}, .meta.${filename}.yaml, or .meta.${filename}.yml exists in the same directory as the document, PureBuilder Simply treats it as an alternative frontmatter and loads it.

This is mainly intended for cases where embedding frontmatter directly in the document is difficult.

For example, when using Pandoc, you may use formats such as text2tag that are neither Markdown nor reStructuredText. Some formats may not provide a way to include metadata. In such cases, you can still attach metadata to the document by using a separate meta file.

Parameters

Frontmatter contains values used by the system as well as values set by the system for convenience.
By utilizing these, you can greatly expand the scope of what can be achieved with static generation while still including dynamic elements.

In the following table, items with Set by = frontmatter mean that the user explicitly specifies them in the frontmatter.
In most cases, this means “if present, the value will be treated as having a special meaning.”

Items with Set by = system mean that PureBuilder Simply automatically sets them.

Parameters