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

A Blessing is a Ruby function or command that PureBuilder Simply invokes before generating the final output file for each document.

The Blessing receives the document’s frontmatter, which includes both user-defined values and those automatically set by PureBuilder Simply.
It can modify this frontmatter, and any changes will be reflected when the template is rendered.

For more details, see Blessing Feature.

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 Hooks 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.

Environment variables

PureBuilder Simply provides Environment variables that able to use in Hooks or Blessing command.