テンプレート

テンプレートシステム

概要

PureBuilder Simplyでページを生成する際にはテンプレートが必要になります。

実際に使用されるテンプレートの形式は、選択したドキュメントプロセッサにより異なります。 多くの場合、eRubyを用いたテンプレートが使われます。

テンプレートシステムを活用すると生成時に動的な要素を組み込むことができます。

テンプレートファイルの指定方法

テンプレートファイルは設定ファイルのtemplateの値として指定することができます。

ここで指定されるテンプレートの種類はドキュメントプロセッサに依存します。

省略した場合、ドキュメントソースルートのtemplate.html(Pandocの場合)もしくはtemplate.erb(eRubyテンプレートシステムを使うもの)が使用されます。

eRubyテンプレートのパラメータ

eRubyテンプレートからは次の変数が見えるようになっています。

ほとんどの場合、frontmatterとarticle_bodyを使います。

さらに使うことは稀ですが、次のインスタンス変数も見えるようになっています。

テンプレートから見る範囲では、@indexesは不完全である可能性が高いです。 なぜならば、@indexesは本来、全ドキュメントを生成したあとに完全な状態になるものであるためです。

インスタンス変数は廃止されたpluginsの機能のために用意された側面が大きく、テンプレートでの利用は推奨されません。 既にこの機能へのeRubyテンプレートからのアクセスはdeprecatedとなっています。

Pandocにおけるテンプレート機能

Pandocをドキュメントプロセッサとして使う場合、Pandocのテンプレート機能が使われます。

Pandocの中ではFrontmatterの値を使った変数展開が可能です。 PureBuilder Simplyには自動的にFrontmatterに追加で値をセットするようになっているほか、Blessingによる介入も可能で、Pandocのテンプレートの機能を積極的に活用します。

Pandocのテンプレート機能についてはPandoc User’s Guide#Templatesを参照してください。

Frontmatter

PureBuilder SimplyにおけるFrontmatter

ドキュメントプロセッサの文脈における “Frontmatter” はほとんどの場合Markdown文書の冒頭に置くことができるYAML形式のメタデータ記述である “YAML Frontmatter” を指します。 ただし、PureBuilder SimplyはYAML Frontmatterに限定せず、統合されたドキュメント単位のメタデータのことを “Frontmatter” と呼んでいます。

メタデータの所在

Markdown YAML Frontmatter

Markdownでは文書の冒頭にYAML形式でメタデータを記載することができます。 これはYAML Frontmatterと呼ばれています。

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

YAML FrontmatterはMarkdownにおける基本的な規則ではありませんが、多くのMarkdownプロセッサが対応しています。

PureBuilder SimplyではMarkdown形式のファイルの場合、ドキュメントプロセッサがYAML Frontmatterに対応しているか否かにかかわらず常にYAML Frontmatterをサポートします。

reStructuredText docinfo

reStructured Textではドキュメント内の最初の非コメント要素がフィールドリストである場合、docinfoというメタデータとして扱うことになっています。

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

PureBuilder Simplyはこれを理解してfrontmatterとして扱うため、もしdocinfoを理解しないreStructuredTextプロセッサが追加されたとしてもfrontmatterとして扱うことができるはずです。

ただし、実際にPureBuilder SimplyでreStructuredTextを使っているユーザーは少ないため、現在の機能で十分に機能するかは不明です。 もし問題がある場合はGitHubのissueにて報告してください。

メタファイル

文書と同一ディレクトリ内に.meta.${filename}もしくは.meta.${filename}.yamlあるいは.meta.${filename}.ymlというファイルが存在する場合、PureBuilder Simplyはこれを代替のfrontmatterとみなしてロードします。

これは主に文書にfrontmatterを埋め込むのが難しい場合に向けたものとなります。

例えばPandocを使用する場合、text2tagなどMarkdownでもreStructured Textでもない形式を使用することができますが、形式によってはメタデータを記載する方法がない場合があります。そのような場合でも分離メタファイルを使用すればドキュメントにメタデータを付与できます。

パラメータ

Frontmatterにはシステムが使用する値や、便宜のためにシステムが設定した値が含まれます。 これを利用することで、動的要素を持つページを静的生成でまかなえる範囲を大きくすることができます。

以下の表においてSet byがfrontmatterになっているものはユーザーがfrontmatterとして明示的に記述することを意味しています。 多くの場合、「存在すればなにか特別な意味を持った値として扱われる」ということを意味しています。

Set byがsystemになっているものはPureBuilder Simplyが自動的に設定するものであることを意味します。