基本概念

Project とノート

Project は、安定した名前空間を持つ1つの配布物です。複数の Anki デッキにノートを配置できます。default_deck が既定の配置先を指定し、Note::deck がノートごとに上書きします。デッキは配置先であり、作成・メディア・ビルドを管理する別のコンテナーではありません。

Note はモデルと内容を保持します。project.add(key, note) は必須の安定したソースキーを割り当て、依存関係をアトミックに収集します。キーの重複、不明なフィールド、モデルやメディアの競合があれば、状態の一部だけを追加することなく失敗します。プロジェクトの名前空間とレコードのキーは、編集やソースの並べ替えを経ても維持してください。表示名や本文は識別キーではありません。

モデル、フィールド、テンプレート

NoteType::builder(key) で宣言を追加し、.build() で検証して共有可能な不変のモデルを返します。model.note() はそのモデルを保持するノートを作成します。組み込みの Basic、Cloze、Image Occlusion のノートは、それぞれ自分のモデルを保持しています。

フィールドとテンプレートには安定キーと任意の表示名があります。Anki での表示名が 正面 でも、テンプレートには {{front}} のようにフィールドキーを記述します。モデルの完成時に、セクション、フィルター、Cloze、ブラウザーテンプレートを含めて参照を検証・コンパイルします。値の代入にもキーを使い、キーの推測や表示名へのフォールバックは行いません。

テキストと HTML

Basic、Cloze、独自のノートのいずれでも、通常の文字列は常に Text として扱います。Text は HTML をエスケープします。意図的にマークアップを含める場合は Content::html を使います。{{c1::answer}} などの Cloze 構文は Text 内で維持されますが、埋め込まれた HTML が信頼済みになるわけではありません。Content::sequence はテキスト、HTML、画像、音声を1つのフィールドにまとめます。

型付きの画像・音声コンテンツは、エクスポートまでメディアの依存関係を保持します。手書きの HTML・CSS・スクリプト用にアセットを明示的に宣言する場合を除き、メディアを文字列へ変換してから追加しないでください。

メディアの所有権

Media は、内容から決定的に導かれるファイル名を持ち、自身でデータを所有するスナップショットです。インポートは、設定された上限内で入力を読み取り検証した後にのみ成功します。その後、元ファイルが変更・削除されても構いません。クローンはストレージを共有し、複数のプロジェクトで使えます。with_export_name は移植可能な固定ファイル名を指定し、既存のクローンやコンテンツノードは変更しません。

型付き参照はメディアを自動収集します。モデルまたはプロジェクトに明示的に指定したアセットは、静的解析で使用箇所を特定できなくても含まれます。任意の HTML やスクリプトからファイルの内容を自動検出することはありません。

ビルドと更新

ビルドに成功すると、APKG の存在が保証された出力を返します。レポートには観測結果が含まれます。スナップショットは JSON データであり、ファイルを所有しません。一時成果物は、少なくとも1つの成果物所有者が残っている間だけ存続します。

更新には、前回配布時のオリジナル APKG に埋め込まれた完全な証拠を使います。独立した比較処理では、検出事項と公開ポリシーを分離します。高リスクの検出事項はデフォルトで更新を停止します。ハードエラーを許可することはできません。Anki のインポート設定、ローカルでの編集、カードの復習スケジュールについては、引き続きクライアントでの確認が必要です。更新とビルドの保証を参照してください。