Boxloom デッキ作成

Boxloom: デッキ作成

Boxloom は 意味 と 見た目 を分離します。コンテンツが 何であるか（ポイントのリスト、オプションの比較、日付付き計画）だけを記述します。テンプレートがすべての色、フォントサイズ、マージン、位置を決定します。唯一の例外（shapes、最後の手段）を除いて、色、サイズ、座標を記述することはありません。

ループは常に以下の通りです：

1. boxloom schema — 現在のテンプレートが受け付ける内容を確認します（最初にこれを行います）。
2. deck.bx.md を記述します。
3. boxloom check -format json deck.bx.md — すべてのエラーを修正し、次に可能な限りすべての警告を修正します。
4. "ok": true かつ layout-overflow 警告がなくなるまで 3 を繰り返します。
5. boxloom build -o deck.pptx deck.bx.md（フラグはファイルの前に指定します）。

コマンドはリポジトリの boxloom/ ディレクトリから実行します： go run ./cmd/boxloom <schema|check|build|parse> …（Go 1.24+、その他の依存関係は不要）。

1. 最初にスキーマを読む

boxloom schema [-template light|dark] は 1 つの JSON ドキュメントを出力します。これが唯一の情報源です。このファイルとスキーマが矛盾する場合、スキーマが優先されます。

• markdown.rules — 構文規則（短いリスト。すべてに従うこと）。
• markdown.frontMatter — --- ヘッダーで許可されるキー（title は必須）。
• templates[].blocks — このテンプレートが認識するフェンス付きブロック（:::name）。inside（配置可能な場所）、contains（中に含めるもの）、minChildren を含みます。
• templates[].subsystems — 図のタイプ（```name コードブロック）。markdown（追加の規則）と schema（許可されるすべてのキーを指す irSchema への JSON ポインタ）を含みます。
• リストにないものはエラーです。ブロック名、属性、キーを独自に作成しないでください。
• テンプレートは名前で選択します（フロントマターで template: light、または -template dark）。カスタムテンプレートはパスで渡される値テーブルファイルです：-template ./my.json（schema、check、build、fonts で機能します。例：examples/templates/forest.json）。デッキをカスタムテンプレートでビルドする場合は、schema と check も同じ -template で実行します。ロール名とテキストスタイルはそのファイルから取得されます。
• variant（# Title {variant=…}）は構文として存在しますが、現在のテンプレートはバリアントを宣言していないため（templates[].variants は空）、使用しないでください。

出力は大きくなります。必要な部分だけを表示するには：

go run ./cmd/boxloom schema -template light > /tmp/schema.json
python3 -c "import json;d=json.load(open('/tmp/schema.json'));print(json.dumps({'rules':d['markdown']['rules'],'blocks':d['templates'][0]['blocks'],'subsystems':[(x['name'],x['markdown']) for x in d['templates'][0]['subsystems']]},ensure_ascii=False,indent=1))"
python3 -c "import json;d=json.load(open('/tmp/schema.json'));print(json.dumps(d['irSchema']['\$defs']['gantt'],ensure_ascii=False,indent=1))"   # すべてのガントキー

2. 1画面でわかる構文

---
title: レポートサービスを新しいクラスタに移行する
subtitle: 計画とオプション（架空の例）
author: プラットフォームチーム
date: 2026-11-11
confidential: 内部
disclaimer: すべての名前と数値は架空です
template: light
---

# 古いクラスタのベンダーサポート

:::lead
古いクラスタは2028年3月にベンダーサポートが終了するため、その上にある14のサービスはそれまでに移行する必要があります。
:::

- ベンダーは **2028-03-31** にセキュリティ修正を終了します
- 14のサービスがまだそこで稼働しています。そのうち9つはコード変更なしで移行可能です
- 移行にはサービスグループあたり約6週間かかります

:::source
2026年9月のベンダーサポート通知、2026年10月時点のサービスインベントリ
:::

:::notes
スピーカーノートはここに記述します。プレーンな段落と箇条書きのみです。
:::

• # Title でスライドを開始します。タイトルは1行に収まる短い見出しにしてください（「古いクラスタのベンダーサポート」）。折り返すタイトルは警告されます（title-wrap）。スライドの内容、つまり結論を、タイトルの直後に :::lead で文として記述します（1〜2行）。テンプレートはリードをタイトルの下、ボディの外側に配置します。

• --- はスライド区切りではありません（エラーになります）。## やそれ以下の見出しはエラーです（グループタイトルは :::column Title と記述します。小見出しではありません）。

• ボディ：段落、- / 1. の箇条書き（最大2レベル）、**強調**（強調は1種類のみ）、`コード`、[テキスト](URL)、意味のある改行のための末尾の \。斜体、取り消し線、脚注、HTML は使用できません。

• フェンス付きブロック：:::name で開始し、同じ数のコロン で閉じます。ネストする場合、外側のフェンスは内側のフェンスよりも 1つ多くコロン を使用します：

  :::::compare
  ::::option 古いクラスタを維持
  :::pros
  - 今年は移行作業なし
  :::
  :::cons
  - 2028年3月以降セキュリティ修正なし
  :::
  ::::
  ::::option 新しいクラスタに移行
  :::pros
  - 2033年までサポート
  :::
  :::cons
  - サービスグループあたり6週間の作業
  :::
  ::::
  :::::
  

• :::lead（スライドのメッセージ）、:::notes（スピーカーノート）、:::source（スライドの数値の出典）は、スライドのトップレベルに、各スライドに1回ずつ配置する必要があります。:::lead はコンテンツスライドのみです。

• フロントマターの date、confidential、disclaimer はデッキ全体で1回だけ記述します。テンプレートはこれらを表紙に配置します（confidential はフッターにも配置します）。すべてのスライドの :::note に「架空」「機密」を繰り返さないでください。

• 図は、言語がサブシステム名であるコードブロックで、ボディは制限付きYAMLです：アンカー/エイリアス（&、*）、タグ、複数行の値、|/> ブロックは使用不可。ブール値は true/false のみ。日付は文字列 YYYY-MM または YYYY-MM-DD。範囲は 2027-01 .. 2027-06。*、&、! で始まる値、または ": " を含む値は引用符で囲んでください。例：text: ["**最も遅いステップ**", 平均5日] — フローアイテムの先頭にある引用符で囲まれていない **…** はYAMLエイリアスとして読み取られ、拒否されます。

3. コンテンツごとのパターンの選択

記述する前に、コンテンツのタイプを決定します。以下のルールを順番に適用し、最初に一致したものを使用します（完全なルールセットと良い例/悪い例は docs/patterns.md §4 を参照）。

現在利用可能なもの（boxloom schema で確認してください。さらに追加されている可能性があります）：

コンテンツ	使用するもの	備考
章の区切り	# Part 2: 移行方法 {type=section}	見出しテキストが章タイトルになります。:::notes 以外は続けてはいけません。目次ではありません。デッキに2つ以上のセクションがある場合、テンプレートはセクションスライドごとに現在のセクションを強調した章リストを描画します
スライドが1文だけを述べ、証拠は他のスライドにある	# 移行は2年早める必要があります {type=statement}	見出しテキストが文そのものです（見出しが完全な文になる唯一のスライドタイプ）。:::notes と :::source 以外は続けてはいけません。理由を追加したい場合は、短いタイトルと結論を :::lead にした通常のスライドを使用します
比較する系列がなく、強く示したい1〜4の数値	::::stat → :::value 3 → 12 {unit=models} + 1行のラベルを内部に	5以上の数値や時系列はチャート/テーブルであり、stat ではありません。値はそのまま記述し、数字を含める必要があります。値と単位は中央で分割されないため、短く保ってください。4つのカードは狭くなります（stat-value）
数値の系列（3+ポイント）：ランキング、経時変化、全体のシェア、分布、2つの量の関係	```chart	compare: item / timeSeries / component / frequency / correlation — チャートタイプは自動選択されます（bar/line/pie と記述しないでください）。categories: [...]、series: [{name, values: [...]}]（カテゴリごとに1つの値、引用符なしの数値、最大3系列）、オプションで unit、emphasis: [category]（1系列）または1つの系列に emphasis: true、系列が全体の一部である場合は stacked: true。correlation はカテゴリの代わりに xAxis: {title, unit?}、yAxis、points: [[x, y], …] を使用します。component（シェア）は1系列で最大6部品。小さな部品は「その他」にまとめてください
他者の言葉	:::quote 出典テキスト + 内部の言葉	出典（見出しテキスト）は必須です。自分の結論を引用しないでください
通常のスライド内で強調する1文	:::takeaway + 1文	スライドごとに最大1つ、通常は最後に配置
プレーンテキストまたは数値の行×列	GFMテーブル：| A | B | + | --- | --- | + 行	最初の行がヘッダーです。すべての行は列ごとに1つのセルを持ちます（table-shape）。配置マーカーは使用不可（:--、--: はエラー）。数値列は自動的に右揃えになります。セルはインラインのみです。テーブルの直後の行 : キャプション がそのキャプションです。最後の行が合計の場合、その行を {total=last} で終了します（: 見積もり {total=last}、または単に : {total=last}）。合計行として描画されます。合計は計算されません。値は手動で記述します。単位はキャプションまたはヘッダーに1回記述し、すべてのセルには記述しないでください。セル内の評価 → matrix（下記）
すべてのセルが評価（対応可 / 条件付き / 不可 / リスク）である行×列	```matrix	columns: [A, B]、rows: [{label, cells: [{status, text?}]}]、オプションで legend: {support: Good}。列ごとに1つのセル（matrix-cells）。推奨オプション：emphasis: <列見出しテキスト>（columns に記述した通り、matrix-emphasis）。文章で「青い列」と表現しないでください。セルがプレーンテキストまたは数値の場合はテーブルであり、matrix ではありません
日付のない3〜7ステップ、方向性がある（あるステップの出力が次のステップの入力になる）	```process	steps: [{title, detail?, status?, emphasis?}]、オプションで caption。番号（1. 2. …）と矢印は自動追加されます。長いプロセスは2行目に折り返されます。status を使用する場合は、legend: {conditional: 承認が必要} でその意味を説明してください（figure-legend）
2つ以上のオプション、それぞれに長所と短所	:::compare → :::option → :::pros / :::cons	3つ以上の共通基準がすべてのオプションに適用される場合、matrix の方が適しています（上記）
子（および孫）を持つ親：チーム構成、所有権	```orgchart	root: {title, detail?}、units: [{title, detail?, members: [{title, detail?}]}]。最大3レベル。ボックスに status を設定する場合は、legend: {conditional: あと2人必要} が必要です。凡例がチャートの下に説明を表示します。:::note で輪郭の色を説明しないでください。無関係なチームを横に並べるのには使用しません
数が減っていく段階（訪問→サインアップ→有料）	```funnel	stages: [{label, value, note?}]、オプションで unit。value は数値またはテキストです。バーの幅は段階的であり、比例しません。段階間の変換率（↓ 45%）は数値から自動的に描画されます。note に記述しないでください。note は段階が減少する理由に使用します。status には legend が必要です。増加する値は警告されます（funnel-increase）。単純なステップには process を使用します
日付付き計画、期間、締切、時間経過に伴うステータス	```gantt	ステータスは support、conditional、none、danger（色ではなくロール）。ハードウェア/サポートリスク期間はグループ risk: A .. B。アノテーションは target を介してグループ/行の id を指します。サブシステムがそれらを配置します
2〜3の並行グループを横に並べて読む（「今年 / 来年 / 実施しない」）	::::columns → :::column グループタイトル（2または3）	各グループは段落、箇条書き、1つのテーブル、1つの画像、1つの ```chart または :::note を含むことができます。ネストされた columns、compare、gallery、その他の図は使用不可。チャートとその読み取りを横に並べる：一方のグループにチャート、もう一方のグループに箇条書きのポイント。幅は数値ではありません。主要なグループに {role=main} をマークします（他のグループはそれを補完します）。またはすべてを等しくします。4つ以上の1行グループは箇条書きにします。1つの議論を2つに分割するのには使用しません
ポイントを示す画像（スクリーンショット、写真、図面）	 のみを含む段落	代替テキストは必須です（image-alt）。パスはデッキファイルからの相対パスです。URL、絶対パス、.. は使用不可（image-path）。PNG または JPEG のみ（image-format）。縦横比は保持され、切り抜きはされません。画像とテキストの横並び → 画像を一方のグループに配置した ::::columns
比較または順序付けられた2〜6の画像	2〜6の  を含む1つの段落	ギャラリーになります（2〜3は1行、4〜6はグリッド）。7以上はエラーです。スライドを分割してください
並列ポイント	箇条書き	最大2レベル
接続された散文	段落	2〜3文
スライドの内容：1〜2文の結論	コンテンツスライドのトップレベルに :::lead、1段落	すべてのコンテンツスライドに配置します。 テンプレートがタイトルのすぐ下、ボディの外側に配置します。ボディから領域を取ります（1行 ≈ 32 pt、2行 ≈ 57 pt）。2行必要な場合、エンジンは文の終わり（。）または、それが不可能な場合はカンマ（、）で改行し、改行を追加しません。そのため、2つの短い文が最も読みやすくなります。箇条書きの要約ではなく、箇条書きが証明する主張です
スライドの数値、テーブル、図、引用の出典（出典、サンプルサイズ、日付）	スライドのトップレベルに :::source、1段落	数値、テーブル、チャート、または引用を表示するすべてのスライドに配置します。 コンテンツスライドとステートメントスライドのみ（セクションは除く）。テンプレートがボディの下、フッターの上に配置します。ボディから領域を取ります（layout-overflow がカウントします）。スライドごとに1つ。複数の出典は1つの段落にまとめてください
デッキ全体の日付、機密性、免責事項（「すべての数値は架空です」）	フロントマターの date、confidential、disclaimer	1回だけ記述。表紙に表示されます（confidential はフッターにも表示）
注意事項 / 脚注のような発言	:::note	短い1行。出典（:::source）には使用不可、デッキ全体の免責事項（フロントマター）にも使用不可、結論や重要な数値にも使用不可
位置やリンクが意味を持ち、上記のどれにも当てはまらない図	```shapes	最後の手段、§3.1 を参照

上記の4つの図すべてにおいて、テキスト、status（support、conditional、none、danger）、emphasis: true のみを記述します。位置、サイズ、色はテンプレートから取得されます。chart では、比較対象と数値のみを記述します。チャートは、値が編集可能な実際のPowerPointチャートです。タイトルが伝える1つのポイントを強調します：

compare: timeSeries
unit: " サインアップ"
categories: [4月, 5月, 6月, 7月, 8月, 9月]
emphasis: [9月]
series:
  - name: サインアップ
    values: [120, 150, 180, 220, 250, 300]

ステータスロール（support、conditional、none、danger）は、gantt、orgchart、funnel、process、matrix のいくつかの要素で使用できます。ロール名はテンプレートから取得されます（boxloom schema で確認可能）。legend は図の下に常に表示されるわけではありません。ロールの意味を凡例で説明する必要がある場合は、legend を使用します。