Phest(PHP Easy Static Site Generator)に関する覚え書き

Phest (フェスト) とは

Phest は PHP Easy Static Site Generator の略らしいです。
手軽に記事を追加できるツールらしいので導入してみたら地獄だった件。

『デザイナ向けの静的サイトジェネレータ』とは、見た目だけ整ったページを生成するツールらしいです。
生成された html を lint で検査したら、"タグが合わねぇ"の警告が山ほど出ました。

そもそも、標準のドキュメント自体、意図した形で生成されてなかった。
記述が悪いのかと思い、サンプルと見比べていたら…… orz
z_phest_document が、製品ドキュメントの元プロジェクトらしいが、最初のページからコケてます。
contents.yml に、ドキュメントを YAML で記述することで、ページを自動生成できますよ〜というサンプルなんですが、コケてます。
"概要"ページの"特徴"セクションの先頭には「### 黒い画面不要！デザイナ向けのツールです。」というタイトル行があります。
これは Markdown記法で <H3>黒い画面不要！デザイナ向けのツールです。</H3> にならなきゃいけない。
ところが、# はYAMLのコメント文のため、行自体がなかった事にされてます。
\ でエスケープできる筈と思ってエスケープしたら、実体参照で、### が生成されてしまいました……

仕方がないので <H3>と直接表記すると、段落と見なされ<P><H3> と出力されました。
ブラウザで見てるだけだと気づかないけど文法的にはダメダメ。
lintに怒られます。閉じタグの</P>の相手が居ねぇ！って。

phest.html(22): 2: <H3> の前に </P> が省略されているとみなします。
phest.html(22): 1: <P> と </P> の間が空です。
phest.html(23): 9: </P> に対応する開始タグ <P> が見つかりません。

• vars.ymlで、includes: [ファイル名, ファイル名, ... ] と、複数ファイルを取り込めるが、YAMLのマージが使えない。
  もともとYAMLにはファイルの読み込み機能がないので仕方ない？
• includes:を複数行書くと、動きが怪しくなる。最後のincludesだけが有効になる模様。
• 拡張子が .html固定。.htm で出力して欲しくても。当然、サイトマップも .htmlで出力される。
  対処：config.ymlに ignoresitemaps: [ regex: custom_error/.*\.html ] と追加する事で、問題のページをサイトマップから除外した。
• エラーチェックが甘い。エラー出力場所が不統一。
  YAML表記部分で記述ミスがあると容赦なく落ちる。
  ライブラリが吐いていると思われる英文メッセージがあれば御の字で、たいていは行番号のみ。php判る人じゃないと使うのは無理だと思う。
  フロントのエラー表示枠が空っぽでも、生成されたページにエラーメッセージが出力されていたりするから油断ならない。
  生成後は全ページの目視チェックが必要。

穴だらけです。
結局、YAMLファイルにはヘッダ・フッタや目次などで使用する文言のみを定義し、本体(本文)は .tpl に直接 htmlで記述する事で落ち着いた。
そうしないと lintでエラーが出る上、記号が化けて、どうしようもない。（メールとシェルスクリプトのページが酷かった）
シェルスクリプトのように記号を多用する文章を markdown で書くのは無理！