テーマ機能

概要

PureBuilder Simplyはその出発点が手書きHTMLを便利にするところにあります。 このため、HTMLやCSSをユーザーが全て書くことができますし、逆に言えばそれらはユーザーが書かなければなりません。

しかし多くのユーザーにとってHTMLやCSSを書くということは容易なことではありません。 PureBuilder Simplyにおける解決策は、「誰かが作ったものをコピーする」です。

これを他のCMSと言葉を合わせるために「テーマ」と呼んでいますが、PureBuilder Simplyにおいては実際のところはプロジェクトテンプレートと呼ぶべきものです。

PureBuilder Simplyのリポジトリにはいくつかのテーマが含まれ、それらはpbsimply-initコマンドによって適用した状態でプロジェクトを開始することができます。

テーマを使う

既存のテーマを使うにはpbsimply-initの-tオプションで使用したいテーマを指定します。

pbsimply-init -t kramdown/init322 foo

これでkramdown/init322テーマが使われます。

テーマはそのテーマで想定しているドキュメントプロセッサごとに分かれています。kramdown/となっているものはKramdownを利用するテーマです。

利用可能なテーマを一覧表示するには-lオプションを使います。

pbsimply-init -l

異なるテーマを適用する

既に存在しているプロジェクトのテーマを変更したい場合は、まず別の場所にそのテーマでプロジェクトを作ります。

pbsimply-init -t pandoc/newtheme bar

そしてそのテーマによってどのファイルが上書きされるのかを注意深く確認し、問題がなければコピー、マージします。

もしもこうした確認を行わなくてもどのように上書きが行われるのかわかっている場合は、-fオプションを使うことができます。

pbsimply-init -f -t pandoc/newtheme foo

ソースファイルだけインストールする

pbsimply-initはデフォルトでSourceとBuildのディレクトリを作ります。

ソースドキュメントルートだけを新しいテーマで更新したいときや、既存のリポジトリを更新したいときなど、Sourceの中身だけをインストールしたい場合は-sオプションを使います。

pbsimply-init -s foo

この場合、foo/Sourceではなくfooにソーステーマがインストールされます。

テーマをインストールする

第三者によって公開されているテーマを利用するには、テーマをまるごと${XDG_CONFIG_HOME:-$HOME/.config}/pbsimply/themes以下にコピーします。 Unix環境では通常は~/.config/pbsimply/themesディレクトリで、存在しない場合は予め作っておきます。 Windowsの場合は同様に%HOMEPATH%\.config\pbsimplyで、エクスプローラのアドレス欄に%HOMEPATH%と打ち込むことから始めるとやりやすいでしょう。

このようにインストールするテーマはドキュメントプロセッサの名前をつける命名規則が適用されません。

第三者によって公開されているテーマは、安全性が保証されません。 自身の責任で内容を確認するようにしてください。

テーマを作る

PureBuilder Simplyのテーマはプロジェクトテンプレートであり、基本的にテーマディレクトリ全体がソースドキュメントルートとしてコピーされます。

テーマディレクトリは.theme.yamlを含んでいる必要があります。 .theme.yamlはテーマに関する情報を持ちます。

キー 値
name テーマ名
author テーマの作者名
description テーマの説明
initial_control インストールで追加で行う処理

initial_controlのbuild_cprは指定されたソースドキュメントルート上のファイルをビルドドキュメントルートへコピーします。 値は文字列配列の配列です。例えば

initial_control:
  build_cpr:
    - [foo, bar]

とすると、Source/foo/barをBuild/barとしてコピーします。

initial_control.build_mkdirpは指定されたディレクトリをソースドキュメントルート上に作成します。 再帰的に作成されるため、事前に上位のディレクトリを用意しておく必要はありません。

initial_control.base_themeが指定されている場合、テーマインストール時にこのテーマをインストールする前にベーステーマをソースへコピーします。

テーマを公開する

テーマはGitHubなど、あなたの好きな場所に公開することができます。

テーマを投稿する

pbsimply-themes-contributeリポジトリは公式のサードパーティテーマのリポジトリであり、このリポジトリにあるものはPureBuilder SimplyのRubyGemsにバンドルされます。

あなたが作った自信作のテーマをこのリポジトリに対してプルリクエストすることで、多くのPureBuilder Simplyユーザーがデフォルトで選択できるテーマのひとつにするチャンスがあります。 ただし、このリポジトリに採用されるためには、以下の基準を満たす必要があります

  • nameは[A-Za-z0-9_.]で構成され、24バイト以下であること
  • descriptionは英語で、簡潔な説明になっていること
  • テーマは<processor>/<name>になるように配置すること
  • ファイル名は[A-Za-z0-9_.-]で構成され、128バイト以下であること
  • テーマが外部との通信を行わないこと
  • 外部ライブラリの導入など、テーマを使用するために通常のインストール以外の作業を要求しないこと
  • テーマはLICENSEまたはLICENSE.txtファイルを持ち、Apache License 2.0と共存できるライセンスを採用すること
最終更新日: 2024-03-31