Blessing feature

Basic Concepts and Usage

PureBuilder Simply makes strong use of document metadata as Frontmatter. This Frontmatter can be referenced from Pandoc templates as well as eRuby templates, and the ability of templates to utilize conditional branches and iterator-like structures allows the output to be radically altered by the Frontmatter. This also allows a single template to produce different forms of output.

PureBuilder Simply itself automatically sets the various Frontmatter. These automatically set elements are pre-built, yet allow dynamic elements to be incorporated into the document.

“Blessing” is an extension of this process of dynamically setting parameters in the Frontmatter. Dynamically extending Frontmatter is the source of PureBuilder Simply’s power, and the Blessing is an extremely powerful extension of that power.

There are two ways to use blessing: as a Ruby library or as a command.

To implement as a Ruby library, place a Ruby script file named .pbsimply-bless.rb on the document source root. This file will be loaded as a library and expects to set PureBuilder::BLESS Proc object.

When blessed, it will be called in the form PureBuilder::BLESS.call(frontmatter, self) to access the frontmatter and an instance of a descendant class of the PBSimply class (the core object of PureBuilder Simply). You can update frontmatter in this process.

To implement it as a command, prepare a blessing command and set the command to bless_cmd in the configuration file. The bless_cmd is the value passed to Ruby’s Kernel.system. It can be an array consisting of a command and arguments, or simply a command line string.

From the blessing command, Frontmatter can be accessed via the path $PBSIMPLY_WORKING_DIR/pbsimply-frontmatter.json. To perform a blessing, rewrite this file. After PureBuilder Simply executes the blessing command, it re-reads the Frontmatter JSON file and updates Frontmatter.

When updating ACCS, the command set to bless_accscmd is called.

Example

This website is available in Japanese and English, and each page can be switched between the two languages. The page for each language can be switched simply by the difference between /en/ and /ja/, but other than the article text, the construction is different for each language.

To achieve this, the following is done in .pbsimply-bless.rb:

  if frontmatter["source_path"].include?("ja/")
    frontmatter["lang"] = "ja"
    frontmatter["lang_specific"] = true
    frontmatter["lang_ja"] = true
    frontmatter["pagelink_en"] = frontmatter["page_url"].sub('/ja/', '/en/')
    frontmatter["pagelink_ja"] = frontmatter["page_url"]
  elsif frontmatter["source_path"].include?("en/")
    frontmatter["lang"] = "en"
    frontmatter["lang_specific"] = true
    frontmatter["lang_en"] = true
    frontmatter["pagelink_en"] = frontmatter["page_url"]
    frontmatter["pagelink_ja"] = frontmatter["page_url"].sub('/en/', '/ja/')
  else
    frontmatter["lang"] = "en"
  end

The lang is set so that the language can be set in the form $lang$, and the lang_ja and lang_en are set so that they can be used for condition separation in the form $if(lang_ja)$. The lang_specific allows the article to be distinguished from the router.