本文へスキップ
mtbmtb

テンプレートを Git で持つ ​

サイトのテンプレートをディレクトリに書き出し、編集して戻せます。

bash
mtb sites templates pull 4 --dir ./templates   # 1テンプレート1ファイル＋マニフェスト
$EDITOR ./templates/スタイルシート.mtml
mtb sites templates push 4 --dir ./templates   # 変わったものだけ戻す

ファイルの配置は MT 自身のテーマの構成に合わせてあります。テンプレートの本文は .mtml ファイルに、 種別や出力ファイル名は mtb-templates.json に記録します。

templates/
├── mtb-templates.json     マニフェスト（種別・出力ファイル名・archiveMaps）
├── メインページ.mtml
├── スタイルシート.mtml
└── ...

これはエンドポイントではありません

Data API に一括の取り出し／書き戻しはありません。mtb が list と update を 繰り返し呼んで実現しています（--all や --dir と同じく mtb 側の機能です）。利用者はテンプレートの操作を sites templates の下で探すので、別の場所に置くより見つけやすいと考えて、 ここに置いています。

約束していること ​

  • ファイルとテンプレートは ID で対応づけます。 MT 側で名前を変えても、手元でファイル名を変えても 対応は保たれます
  • 変わっていないものは送りません。 1つ直しただけで全件に新しいリビジョンが記録されると、 MT の更新履歴が役に立たなくなります。本文だけでなく名前・出力ファイル名・ buildType・linkToFile の変更も検出します
  • MT にあって手元に無いテンプレートは操作しません。 件数と名前を報告するので、 消すなら sites templates delete を明示的に使ってください
  • マニフェストに id の無い項目を書くと新規に作成し、採番された ID を書き戻します
  • 種別は新規作成のときだけ送ります。 既存テンプレートの種別は変えられません （システムテンプレートでは受け付けられません）
  • マニフェストの siteId が対象のサイトと違えば、処理を中止します（別のサイトを誤って上書きしないため）

アーカイブマッピングも往復します ​

アーカイブマッピングはマニフェストの archiveMaps に記録されます。マッピングは URL の設計そのものなので、 これが無いと pull したディレクトリから出力先（blog/%-b.html など）を戻せません。

本文が変わっていなくても、マッピングだけ変わっていれば送ります。

マッピングを扱うのは individual / page / archive / ct / ct_archive の種別のテンプレートだけで、 それ以外の種別ではマッピングを問い合わせません。

上書きに注意 ​

pull は手元のファイルを上書きします

先に commit するか、--dry-run で確かめてください。 push は書き換える件数を示して確認を求めます（--yes で省けます）。

Git に置くと何が良いか ​

  • レビューできる。 テンプレートの変更が普通の差分として読めます
  • 戻せる。 MT の更新履歴に頼らずに、リポジトリの履歴から戻せます
  • CI から反映できる。 マージしたら push する、という運用にできます （デザインを Git と CI で管理する）

外部ファイルとのリンクという選択肢 ​

サーバのファイルシステムに直接アクセスできるなら、テンプレートを外部ファイルと リンクするほうが MT 公式の仕組みで、pull/push は要りません。

bash
mtb sites templates update 4 96 --set template.linkToFile=/path/to/file.mtml
向いている場面
pull / pushサーバのファイルにアクセスできない。共用サーバ・マネージド環境
linkToFileサーバに rsync できる。デプロイの経路が既にある
テーマサイトを丸ごと構築する。設計をパッケージとして配布する

スタイルシートと JavaScript はテンプレートです ​

JS と HTML はアセットにできません

MT の DeniedAssetFileExtensions が既定で拒否します（js html htmshtml ほか）。'.js' is not allowed to upload by system settings. が出たら、 この設定が原因です。

MT の作法では、スタイルシートと JavaScript はインデックステンプレートです。

bash
mtb sites templates create --site-id 4 \
  --set template.name=テーマJS \
  --set template.type=index \
  --set template.outputFile=theme.js \
  --set template.text=@dist/theme.js

画像・CSS・SVG・フォント・webp はアセットとしてアップロードできます。

テンプレートを試す ​

捨て用のテンプレートも、サンドボックスのサイトも要りません。preview はテンプレートIDを省くと、保存せずに本文だけを評価します。

bash
mtb sites templates preview 6 --set template.text=@snippet.mtml \
  --set template.type=index --raw 1 --extract preview
  • IDを付けると既存テンプレートのプレビューになります
  • --raw 1 を付けないと HTML がエスケープされて返ります
  • 同じ形が sites entries preview / sites pages preview にもあります

タグの綴りを1つでも間違えると、プレビュー全体が 500 になります。ただし、エラー本文に「認識できないタグ」が すべて列挙されるので、候補をまとめて1回で試すと少ない回数で済みます。

次は ​

Last updated: