Learn More

Introduction

This article provides a bird’s-eye view of the knowledge required to use PureBuilder Simply in depth.

For detailed individual specifications, please refer to README.

Project and Document root

PureBuilder Simply handles two directories: the “document source root” where documents such as Markdown and ReST are placed, and the “document build root” where HTML files built by PureBuilder Simply are placed.

Until v3.2.1, the pbsimply command was to be executed on the document source root. This has changed in v3.2.2 so that it can be executed anywhere in the document source root. However, it is still recommended to execute them on the document source root, as they are only considered to be executed on the document source root.

The document source root is simply the directory where the .pbsimply.yaml file is located. In contrast, the document build root is the directory configured in .pbsimply.yaml.

The default configuration of .pbsimply.yaml specifies ./Build as the build directory, so the document source root and document build root default to being on the same directory. We call this the PureBuilder Simply project directory for convenience. However, there is no restriction that the project directory must be set up.

pbsimply command

The pbsimply command is a Ruby executable, and a Gems executable if installed with RubyGems. In some cases, you may need to configure the RubyGems bin directory to be included in the PATH.

The pbsimply command has command line options -f, -I, -A, -o FILE, and -m FILE, but only -f is used in most cases.

With the -f option, it will build even if it determines that there are no updates.

The typical case when the -f option is needed is when you update a template. Since pbsimply does not detect template updates, you must rebuild all articles with the -f option after updating a template.

Sub directories and ACCS

The argument to pbsimply can be a file or a directory. If a file is given, only that file will be built; if a directory is given, all files in that directory will be built. If a directory is given, no recursive build is performed, and the single-layer directory is treated as a single set of articles.

The directory structure under the document source root is a path structure as it is when serving as a static file, but for convenience of build and management, it is preferable to separate the directories appropriately.

ACCS is the main reason why it is preferable to handle PureBuilder Simply on a per-directory basis.

ACCS is a PureBuilder Simply feature for handling “series of articles”. It is automatically enabled when you build the directory where .accs.yaml is placed.

When ACCS is enabled, it automatically sets next_article and prev_article in frontmatter and builds index.html of the directory. This behavior is programmable and a bit complicated.

The next_article is set by PureBuilder::ACCS::DEFINITIONS[:next] proc and the prev_articles is set by PureBuilder::ACCS::DEFINITIONS[:prev] proc.

If blessmethod_accs_rel is set, the default algorithm is used. How the default algorithm sorts files to determine previous/next depends on the value of the setting. numbering sorts the first part of the filename as a number. date sorts based on date. timestamp sorts filenames by timestamp. lexical sorts filenames in lexical order.

The ACCS index.html is built using an eRuby file named .accsindex.erb placed on the ACCS directory or on the document source root. If neither is present, the default eRuby template is used.

The default ACCS templates classify by category and sort by date. The category is used by the default ACCS functionality, but not by the PureBuilder Simply built-in (non-overrideable) functionality.

Also, the default ACCS template can switch between ascending and descending order by accs_order in the configuration file.

Domation fixed absolute path

The files configured in PureBuilder Simply are not as restricted in file placement and paths as a typical CMS and can be freely configured by the user. For this reason, PureBuilder Simply does not complete paths on its own.

When editing PureBuilder Simply source document, the document source root becomes a virtual /. And the / in the source document link becomes the root of the domain. If https://www.example.com/ is equal to the document build root, then you can consider the document source root to be / and write links starting with / to be consistent in all places.

For example, suppose you have img/logo.png from the document source root. To put this image, use the

![logo](/img/logo.png)

to link to it.

This is also convenient because Visual Studio Code (=VSCode) (or Code OSS) will complete the file path and display it in the markdown preview if it is written in this format.

If the public path on the web server is a subpath not in the root, such as https://www.example.com/foo, there are two methods.

The easier and more convenient of the two is to provide a sub-directory on the document source root that is the same as the public path.

To match a file configured using pbsimply-init to https://www.example.com/foo, the file arrangement would look like this

.accsindex.erb
.pbsimply.yaml
foo/articles/.accs.yaml
foo/articles/20231028-untitled.md
foo/css/style.css
foo/index.md
menu.yaml
template.erb

When you build files placed in this way, only foo will be created in the document build root, and all build files will be created under foo. Files such as images should also be placed under foo.

You can now upload the contents of the foo directory to the root of the public source to maintain consistency.

The problem with writing in paths starting with / is that it is not possible to open the built HTML file as a local file to check it.

PureBuilder Simply provides the pbsimply-testserver command for such a check. Running this command in the document source root will start a local web server and serve the built file.

Blessing

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.

Hooks

Hooks are additional Ruby functions called during PureBuilder Simply processing. Hooks allow you to add additional behavior to PureBuilder Simply’s processing.

To configure Hooks, define PBSimply::Hooks.load_hooks by .pbsimply-hooks.rb on the document source root. Unlike Bless, it can only be written in Ruby.

The load_hooks is passed a Hooks object as an argument. The Hooks object has accessor methods pre, post, process, and delete, all of which return timing objects.

The timing object has four methods: add, <<, cmd, and filter. The add and << are for executing Ruby code, while cmd and filter are for executing external commands.

Please refer to the README for specific usage.

While Bless was for editing document metadata, Hooks is for editing the document itself or acting on something other than the document. For example, the pbsimply-searchutils plugin uses Hooks to generate a search index.

Last updated: 2024-03-31