obsidian-dev-rules

Obsidian 開発ルール

Obsidian は プラグイン（Obsidian API を使用する TypeScript）と テーマ／スニペット （CSS）の 2 つの方法で拡張できます。このスキルは https://docs.obsidian.md の公式開発ドキュメントに沿っており、ドキュメントを再取得せずに Obsidian のプラグイン／テーマを開発・レビューできます。API は obsidian npm パッケージとして提供されており、標準的な出発点は obsidian-sample-plugin です。

このスキルを使う場面

• Obsidian プラグインの開発、デバッグ、レビュー（ライフサイクル、コマンド、設定、UI、ビュー）。
• Vault API でノートを読み書きする場合や、Editor API でアクティブなノートを操作する場合。
• イベントの購読、Markdown ポストプロセッサー／コードブロックプロセッサーの登録、または CodeMirror 6 エディター拡張機能の開発。
• テーマ（CSS 変数、theme.css、マニフェスト）やスニペットの開発。
• コミュニティディレクトリへのプラグインまたはテーマのリリース／申請。

リファレンス一覧 — 必要なファイルを読み込む

ファイル	内容
references/plugin-basics.md	プロジェクトのセットアップ、manifest.json、プラグインのライフサイクル（onload／onunload）、リソースの登録とクリーンアップ、イベント、開発ワークフロー／ホットリロード、デバッグ
references/vault-and-editor.md	Vault API（read/cachedRead/create/modify/process/delete、TFile/TFolder、アダプター、normalizePath）、Editor API、Markdown のポストプロセスとコードブロックプロセッサー、CodeMirror 6 エディター拡張機能
references/ui.md	コマンド（コールバックのバリエーション、ホットキー）、設定（PluginSettingTab、load/saveData、Setting コントロール）、モーダル（Modal/SuggestModal/FuzzySuggestModal）、ビュー（ItemView、registerView、ワークスペースのリーフ）、リボン／ステータスバー
references/themes-and-release.md	テーマ（CSS 変数、theme.css／マニフェスト、body クラス、スニペット）、プラグインとテーマの申請、開発者ポリシーとガイドライン

チートシート

import { Plugin, Notice, MarkdownView, TFile, normalizePath } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    await this.loadSettings();
    this.addRibbonIcon('dice', 'Greet', () => new Notice('Hello!'));
    this.addCommand({ id: 'do-x', name: 'Do X', callback: () => {/* ... */} });
    this.addSettingTab(new MySettingTab(this.app, this));
    // Auto-cleaned on unload — always register through these:
    this.registerEvent(this.app.vault.on('modify', (f) => {/* ... */}));
    this.registerInterval(window.setInterval(() => {/* ... */}, 1000));
    this.registerDomEvent(document, 'click', () => {/* ... */});
  }
  onunload() { /* release anything NOT registered via register*/ }
}

// Vault: prefer process() over read()+modify(); use cachedRead() for display only.
const file = this.app.vault.getFileByPath('Notes/x.md');
await this.app.vault.process(file, (data) => data.replace('foo', 'bar'));
// Editor of the active note (preserves cursor/selection):
const view = this.app.workspace.getActiveViewOfType(MarkdownView);
view?.editor.replaceSelection(view.editor.getSelection().toUpperCase());

プラグインファイル：manifest.json + main.js（+ 任意の styles.css）を <vault>/.obsidian/plugins/<id>/ に配置します。 テーマファイル：manifest.json + theme.css を <vault>/.obsidian/themes/<name>/ に配置します。

厳守事項

• グローバルの app ではなく、必ず this.app を使ってください（グローバルはデバッグ用にのみ存在し、削除される可能性があります）。
• 後処理が必要なものはすべて registerEvent / registerInterval / registerDomEvent / addCommand / registerView / registerMarkdownPostProcessor で登録してください。Obsidian はプラグインのアンロード時にこれらを自動でクリーンアップします。それ以外は onunload() で手動解放してください。リスナーやインターバルのリークは、プラグインを無効化した後に Obsidian の動作を低下させます。
• 動的なコンテンツに対して innerHTML / outerHTML / insertAdjacentHTML を決して使わないでください。createEl() / createDiv() / createSpan() で DOM を構築してください。
• Adapter API より Vault API を優先してください。全件を反復せず getFileByPath() を使い、ユーザーが指定したパスは必ず normalizePath() で正規化してください。データ損失を防ぐため、read() と modify() を順番に呼び出す代わりに process()（アトミック）を使ってください。cachedRead() は読み取った内容を書き戻さない場合に限り使ってください。
• アクティブなノートは Editor インターフェース経由で編集してください。Vault.modify ではカーソルと選択範囲が保持されません。
• ビューインスタンスへの参照を保持しないでください。Obsidian がビューを再作成する場合があるため、getLeavesOfType() / getActiveViewOfType() で取得してください。
• 配布するプラグインには デフォルトのホットキーを設定しないでください（OS に依存し、競合しやすいため）。UI テキストは センテンスケースにしてください。ハードコードしたインラインスタイルではなく、CSS クラスと Obsidian の CSS 変数を使ってください。
• manifest.json の必須フィールド：id、name、version（semver x.y.z）、minAppVersion、 description、author、isDesktopOnly。id に「obsidian」を含めてはいけません。name は Basic-Latin 文字を使い、ハイフン以外の絵文字や句読点を含めてはいけません。
• リリース：タグがマニフェストの version と一致する GitHub リリースを作成し、main.js、 manifest.json、任意の styles.css を、ZIP にまとめず 個別のバイナリーアセットとして添付してください。
• Promise チェーンではなく async／await を使ってください。var ではなく const／let を使ってください。