Using Theme

Synopsis

PureBuilder Simply’s starting point is to make handwritten HTML convenient. Therefore, users can write all the HTML and CSS, or conversely, they must write them.

However, writing HTML and CSS is not an easy task for many users. The solution in PureBuilder Simply is to “copy what someone else has created.”

We call this a “theme” to make the terminology more consistent with other CMSs, but in PureBuilder Simply it should really be called a project template.

The PureBuilder Simply repository contains several themes, which can be applied by the pbsimply-init command to start a project with them applied.

Use Theme

To use an existing theme, use the -t option of pbsimply-init to specify the theme you wish to use.

pbsimply-init -t kramdown/init322 foo

This will use the kramdown/init322 theme.

The themes are separated by the document processor assumed by that theme. The kramdown/ theme is the one that uses Kramdown.

Use the -l option to list the available themes.

pbsimply-init -l

Install source files only

pbsimply-init creates Source and Build directories by default.

If you want to install (source) theme into Source, use -s option.

pbsimply-init -s foo

This command installs source theme into foo not foo/Source.

Apply different theme

If you want to change the theme of an already existing project, first create a project with that theme elsewhere.

pbsimply-init -t pandoc/newtheme bar

Then carefully check which files are overwritten by the theme, and if all is well, copy and merge.

If you know how the overwrite will be done without this check, you can use the -f option.

pbsimply-init -f -t pandoc/newtheme foo

Install theme

To use a theme published by a third party, copy the entire theme under ${XDG_CONFIG_HOME:-$HOME/.config}/pbsimply/themes. In Unix environment, it is usually ~/.config/pbsimply/themes directory, and if it does not exist, create it beforehand. On Windows, it is similarly %HOMEPATH%\.config\pbsimply, and it is easier to start by typing %HOMEPATH% in the Explorer address field.

The naming conventions for naming document processors do not apply to themes installed this way.

Themes published by third parties are not guaranteed to be secure. Please verify the contents at your own risk.

Create theme

PureBuilder Simply themes are project templates and basically the entire theme directory is copied as the source document root.

The theme directory must contain .theme.yaml. The .theme.yaml contains information about the theme.

キー	値
`name`	Name of theme
`author`	Name of author
`description`	Theme summery
`initial_control`	Additional action in appling theme

The build_cpr of initial_control copies files on the specified source document root to the build document root. The value is an array of string arrays. For example

initial_control:
  build_cpr:
    - [foo, bar]

would copy Source/foo/bar as Build/bar.

initial_control.build_mkdirp creates the specified directory on the source document root. Since it is created recursively, there is no need to prepare a parent directory in advance.

initial_control.base_theme sets “base theme”. If it’s set, copy base theme into document source directory before installing this theme.

Publish theme

You can publish anywhere you want (e.g. GitHub.)

Contribute theme

The pbsimply-themes-contribute repository is the official third-party theme repository, Anything in this repository will be bundled with PureBuilder Simply’s RubyGems.

By making a pull request to this repository for a theme that you are confident in creating, you have the opportunity to make it one of the default choices for many PureBuilder Simply users. However, to be accepted into this repository, your theme must meet the following criteria

name must consist of [A-Za-z0-9_.] and less than or equal to 24 bytes
The description must be in English and be a concise description
Themes should be placed so that they are <processor>/<name>.
The file name should consist of [A-Za-z0-9_.-] and must be less than or equal to 128 bytes.
The theme must not communicate with the outside world.
The theme does not require any work other than normal installation to use it, such as installing external libraries.
The theme must have a LICENSE or LICENSE.txt file and adopt a license that can coexist with the Apache License 2.0