テーマをインポートする

テーマをインポートする

bxSites theme:import は、他の静的サイトジェネレーターのエコシステムの テーマを、themes/<name>/ 配下の bx-sites テーマスキャフォールドへと ベストエフォートで変換します - これは出発点であり、ロスレスなワンコマンド 移植ではありません。テーマ構造が bx-sites 自身の layout.bxm+page.bxm 契約に対応付けられる 3 つのエコシステムをサポートしています（テーマ を参照）:

• mkdocs - Jinja2 テンプレート（純正の mkdocs も mkdocs-material も ともに base.html+main.html を使用）
• jekyll - Liquid テンプレート（_layouts/default.html+ _layouts/page.html）
• hugo - Go テンプレート（layouts/_default/baseof.html+ layouts/_default/single.html）

React/Vue コンポーネントベースのテーマ（Docusaurus、VuePress、Gatsby な ど）には、ここでの対応物がありません - テーマがサーバーレンダリングされた マークアップではなくコンパイル済みの UI コンポーネントであるため、機械的 に変換できるテンプレートファイルが存在しないからです。これらのいずれか を移植するには、ゼロからテーマを書く の要領で bx-sites テーマとしてゼロから書き直す必要があります - 変換では ありません。

bxSites theme:import --source=mkdocs --path=/path/to/mkdocs-theme --name=my-imported-theme

• --source（必須）- mkdocs、jekyll、hugo のいずれか
• --path（必須）- 変換元テーマ自身のルートフォルダ（レイアウトテンプ レートを含むフォルダであり、mkdocs/jekyll/hugo のプロジェクト全体で はありません - プロジェクトのコンテンツを変換する方法については mkdocs からの移行/ GitBook からの移行 を参照してください。 テーマの変換とは別の作業です）
• --name（必須）- 変換先の名前。themes/<name>/ に書き込まれます （install:theme が使用するのと同じ インストール済みテーマの規約 です）- 結果に満足したら bxsites.yaml の theme.name にこの名前を 設定してください

同じ --name に対して再実行しても安全です - layout.bxm/page.bxm は 上書きされ、新しく見つかったアセットフォルダはマージされます。反復作業 （変換元やマッピングを調整して再実行する）が通常のワークフローであり、 一度きりの操作ではありません。

実際に何が変換されるか

コマンドの出力は、実際に何が起きたかを正確に報告します - どのソース ファイルが layout.bxm/page.bxm になったか（あるいは、変換元テーマが 上記の慣習的なファイル名のいずれも使っていない場合はその旨の注記）、 どのアセットフォルダ（css/、js/、static/ など）が themes/<name>/assets/ にそのままコピーされたか、そして手動で確認が必要なものすべての番号付き リストです。

テンプレートファイル内では、これは機械的でベストエフォートな トランスレーターです（mkdocs/jekyll が共有する Jinja2/Liquid 構文には JinjaLikeTranslator.bx、hugo の Go テンプレートには GoTemplateTranslator.bx）- どちらの言語についても本物のパーサーでは ありません。処理される内容:

• 変数出力（{{ page.title }} / Hugo の {{ .Title }}）。ページタイトル/ コンテンツ/説明、サイト名/説明、ベース URL、ナビゲーションといった 一般的なフィールドの小さな固定テーブルに対してマッピングされます - このテーブルの範囲外のものは、推測されることなく <!--- TODO: ... ---> マーカーとして残されます。
• if/elif/else/endif（mkdocs/jekyll）または if/else if/else/end（hugo）は、実際の <bx:if>/<bx:elseif>/<bx:else> 構造に変換されます - 条件自体が マッピングテーブル外の何かを参照している場合でも、常に構造的には有効 です（その場合は代わりに警告としてフラグが立てられます。周囲の if 自体を壊れたままにするより、人が確認すべき条件を残すほうがましだから です）。
• for x in list/endfor（mkdocs/jekyll）または range/end（hugo）は、 同じように <bx:loop> に変換されます。Hugo の range は、一般的な ケースでは名前付きループ変数なしに . を各要素に再バインドします - 生成される <bx:loop> は常に合成された item という名前を使い、 ループ本体内の裸の .Field は Go におけるレンジ要素自身のフィール ドを意味するという固定の警告が表示されます（これは自動的に item.Field へ再ターゲットすることはできません）。
• コメント（Jinja2/Liquid の {# ... #}/{% comment %}、Go の {{/* ... */}}）は完全に削除されます。

意図的に変換されないもの。常に TODO マーカーとして残されます（あるいは、 未変換の生の構文をそのまま残すと不正な BoxLang になってしまう条件式の内部 では、構文的に安全なプレースホルダーに置き換えられます - 条件式には false、ループのリスト式には [] - 同じ方法でフラグが立てられます）:

• フィルター/パイプライン（{{ page.title | upper }}、 {{ .Title | truncate 100 }}）- フィルターのセマンティクスは多様 すぎて安全に推測できません。とはいえ、明らかに安全な BoxLang の対応物 を持つフィルター（upper → ucase()）はよくあるパターンなので、 手早く手動修正できることが多く、確認する価値はあります。
• テンプレート継承（Jinja2 の {% extends %}/{% block %}、Hugo の {{ block }}/{{ define }}）とインクルード/パーシャル（{% include %}）
  • これらを bx-sites 自身の単一ファイル layout.bxm+page.bxm 契約に 自動的にマッピングする方法はありません。
• Hugo の {{ with .X }} - 自身の本体のために . を新しいコンテキスト にバインドします。bx-sites には対応物が全くないため、構造的には有効 だが意味的には誤った <bx:if> として出力するのではなく、未変換の まま残されます。
• 単一のフィールド参照ではない Go の条件式（Go はブール論理を前置関数 呼び出しとして書きます - {{ if and .A .B }}、 {{ if eq .Type "post" }} - これらには BoxLang の中置演算子に相当する ものがありません。.Field トークンだけを置き換えても不正な BoxLang テキストが残ってしまうため、代わりに条件式全体がプレースホルダーに 置き換えられます）。
• 固定マッピングテーブルにない変数参照すべて。

インポート後にすべきこと

このスキャフォールドは出発点であり、完成したテーマではありません - 報告された TODO マーカーと警告に一つずつ対処し、その後、手書きのテーマ と同じようにThemeProvider 契約 （layout.bxm+page.bxm が必須、search.bxm は任意）と照らし合わせて 確認してください。ダークモード、パンくずリスト、前後ページリンク、 検索ボックスなど、すべての組み込みテーマが実装しているページ機能の 規約は、自動的には付いてきません - 変換元テーマにそれらに相当する独自の マークアップがあった場合、それも他のすべてと同じ機械的な変換を経ている ため、同じ確認が必要です。