本文へスキップ
mtbmtb

テーマからサイトを起こす ​

テンプレートを Git で管理し、ファイルからサイトを構築する進め方です。 サイトを構築してから export-theme で書き出す方法とは向きが逆で、 テーマが原本で、サイトはテーマを適用した結果になります。Git の履歴がそのまま設計の履歴です。

使えるかどうかを先に確かめる ​

Data API ではテーマをインストールできません

/themes にあるのは取得・削除・適用と書き出しだけで、install も upload も ありません（実機の 266 エンドポイントで確認）。ファイルをサーバに置く手段が 別に要ります。

置く手段
rsync / scpこれが使えるなら、この進め方が最も適しています
管理画面のテーマインストールzip を人間がアップロードする。CI には向きません
どちらも無いこの進め方は採れません。 テンプレートの pull/push を使ってください

置き場所 ​

theme-v1/
  theme.yaml                    何を持つテーマかの定義
  templates/*.mtml              テンプレートの本文
  blog_static/<フォルダ>/...     静的ファイル（CSS・画像・フォント）

静的ファイルは blog_static/ の下です

static/ のような名前のディレクトリに置いてもサイトに取り込まれず、エラーも警告も出ないまま 404 になります。

theme.yaml ​

実機で動作を確かめた最小の構成です。

yaml
id: mtb_v1                        # ディレクトリ名と合わせる
name: mtb v1
version: '1.0'
class: website                    # blog なら blog
elements:
  template_set:
    importer: template_set
    data:
      base_path: templates        # .mtml の置き場所
      label: mtb v1
      templates:
        index:
          main_index:             # ← templates/main_index.mtml
            label: メインページ
            outfile: index.html
            rebuild_me: 1
        archive:
          entry_archive:
            label: 記事アーカイブ
            mappings:             # ここに書けばアーカイブマッピングも入る
              individual:
                archive_type: Individual
                preferred: 1
        module:
          header:
            label: ヘッダー
  blog_static_files:
    importer: blog_static_files
    data:
      - static                    # blog_static/static/ を運ぶ

mappings を書けば、アーカイブマッピングも一緒に作成されます。 書かないと 記事の個別ページが出力されず、あとから手で作ることになります。

配置と適用 ​

bash
rsync -a theme-v1/ prod:/path/to/themes/mtb_v1/        # 置く（mtb の外）
mtb themes list --profile prod --fields id,label       # 見えるか
mtb sites themes apply <site> mtb_v1 --profile prod --yes --confirm "<サイト名>"
mtb sites templates publish <site> <index-tid> --profile prod
curl -s -o /dev/null -w '%{http_code}\n' http://<host>/

適用はテンプレートの総入れ替えです

テーマを適用すると、そのサイトのテンプレートは全件 backup 型にリネームされ、 アーカイブマッピングは削除され、出力ファイル名も消えます （MT::Theme::TemplateSet::apply）。テンプレートを作り込んだ後に適用すると、 URL の設計からやり直すことになります。マニュアルの適用ページに警告はありません。

テーマは最初に適用してください。 mtb は --yes に加えて --confirm <サイト名> を要求します。

確かめる ​

API が success を返すことと、ページが正しく出力されていることは別です。

bash
curl -s http://<host>/ | grep -c '</mt:'      # タグの閉じ漏れ（0 であること）
mtb dump --profile prod --dir ./after         # 入ったものの一覧

</mt: が本文に出ていたら、ブロックタグでないものをブロックとして書いています。

テーマが運べるもの ​

sites export-theme --include の選択肢がそのまま「テーマが持てるもの」です。

template_setテンプレートとアーカイブマッピング
blog_static_files静的ファイル
custom_fieldsカスタムフィールドの定義
default_categories / default_folders / default_category_sets初期の分類
default_content_typesコンテンツタイプの定義
be_block / be_config / be_prefブロックエディタのカスタムブロック

カスタムブロックはテーマでしか運べません

Data API にエンドポイントが1つも無く、ダンプにも出ないので、 差分にすら現れません。カスタムブロックを使っているサイトを移行するときは、必ず含めてください。

記事・ページ・アセットはテーマでは運べません（テーマが持つのはサイトの枠組みで、コンテンツは含みません）。

サイトから書き出す場合の落とし穴 ​

--include blog_static_files だけでは静的ファイルが含まれません

どのフォルダを含めるかはサイトの theme_export_settings に保存されている 必要があり、Data API からは設定できません（管理画面のテーマエクスポート画面で フォルダ名を1行ずつ入れて保存します）。

保存が無くても status は success を返すので、空のテーマができたことに 気づけません。 実機で確認済みです。

bash
mtb sites export-theme 4 --theme-id my-theme --theme-name "My Theme" \
  --include blog_static_files,template_set --overwrite-yes 1

詰まったら ​

症状見るところ
静的ファイルが 404blog_static/ の下に置いているか
記事の個別ページが出ないtheme.yaml に mappings を書いたか
適用が --confirm を要求する正しい挙動です。サイト名を確かめてから入力する
テーマが themes list に出ないディレクトリ名と id が一致しているか。ウェブサーバから読めるか

繰り返し適用すると backup が増えていきます

適用のたびに旧テンプレートが backup 型にリネームされて残ります。 一覧には出ず、API からは削除できません（403 Cannot delete backup template.）。 実機で2回適用したら 53 件中 38 件が backup でした。

開発中は使い捨てのサイトで試し、本番では管理画面から削除してください。

次は ​

Last updated: