🕊

ゼロから始めるObsidianプラグイン開発-01

2021/09/26に公開約12,800字

はじめに

久しぶりのZennの記事ですが、Obsidian October 2021のイベント開催を記念してObsidianでのプラグインの作り方を紹介したいと思います。偶然なのですが、ちょうど自分も初のプラグインを作成しコミュニティプラグインとしてリリースしたので、自分自身のアウトプットも兼ねてプラグイン開発についてゼロから説明する記事にしたいと思います。

今回は、初心者の方がプラグインを作ってみたいと思った時に役立つ開発のやり方と公開までのロードマップを初歩から解説します。長い話になるので複数回の記事にする予定で、これが第一回目となります。

イベントの詳細については下のリンクから確認してください。

https://publish.obsidian.md/hub/11+-+Events/Obsidian+October+2021

対象読者

  • Obsidianのコミュニティ開発に興味ある方
  • Obsidianに限らずツールのプラグイン開発に興味ある方
  • ノンプログラマーだけど開発をやってみたい方

今回の記事の内容

第一回の記事では、プラグインシステムの基礎とサンプルプラグインを実際に動かすところまでを説明していきます。例の如く、記事公開後も内容追加していきたいと思いますので注意してください。

環境

開発を行っているのはM1チップのmacOS Big Sur v11.3です。windowsやlinux版については解説しませんので注意してください。

  • obsidian API: v0.12.0
  • Obsidian Sample Plugin: commit hash c228a70

プラグイン開発の前に

必要な前提知識

僕の開発開始の初期状態に合わせると、コミュニティリリースを目指したプラグイン開発に最低限必要な知識は以下の3つの項目です。

  1. HTML/CSS/Javascriptがある程度わかる
  2. ターミナルやVScodeなどをある程度使える
  3. git/githubを使ったことがある

開発の中枢となるHTML/CSS/Javascriptはある程度わかっておかないとそもそも開発は難しいので、全く触ったことがないという方は、カスタムテーマの改造やカスタムCSSスニペットからはじめてみるのがオススメです。

https://publish.obsidian.md/hub/09+-+Digital+Garden/09.02+-+How+To/Guides/Themes/How+to+Style+Obsidian

ObsidiainのカスタムCSSの改造やターミナルコマンドなどについては以下の自分のブログ記事で説明したので興味がある方は読んで見てください。

また、かなり遠回りになりますが、静的サイトによるブログやAnkiなどで簡単なHTML/CSS/Javascriptをゼロから作りながらある覚えたので並行でそういったことをやってみるのもオススメです。

https://apps.ankiweb.net

https://gohugo.io

実際のプラグイン開発ではJavascriptのスーパセットであるTypescriptという言語を使用しますが、Javascriptをある程度触ったことがあれば、他のプラグインを見てからほしい機能の実装参考にする程度で簡単なプラグインは作ることができました。(具体的にはCSSの制御とコマンドを実装するなど)

ちなみにtypescriptで書く処理部分よりも環境やらの方が開発の最初ではハードルとなっていました。

なので、最初はそこまで恐れる必要はないと思います。作るのと平行に調べながらやっていきましょう。

使用する技術はいわゆるweb技術と呼ばれる領域のものです。英語ですが以下の動画でそれぞれがどのように関連しているかわかり易く説明されています。使用する技術スタック(HTML/CSS/SASS/JavaScript/Git/npmなど)についてなんとなく雰囲気を掴むことができます。興味がる人は見てみると良いと思います。

具体的ステップアップ

さて、「ゼロからはじめる」という話ですが、さすがにいきなりプラグインを開発することは難しいので、上記の前提知識を獲得できるように徐々にステップアップしていくのをオススメしています。僕の場合はプラグインを作り始める前に以下のステップを踏んで開発できるようになりました。かなり小さくステップアップしていったということもあり、時間がかかってしまうのであまり参考にならないかもしれませんが、プラグイン開発をいきなり始める前にいくつかやってみるといいかもしれません。プログラムをかけるならそもそもこれらのプロセスは省いていいと思います。

  1. ドキュメント翻訳でGitを使ってみる
  2. イシューやバグレポートなどを作成してみる
  3. 他の人が作ったコミュニティプラグインに小さい機能をプルリクエストしてみる
  4. カスタムCSSスニペットを開発して公開してみる

自分の場合はGithub自体は使ったことがありましたが、プルリクエストはやったことがないという状態からはじめました。プルリクエストやgitになれると開発のやり方がだんだんわかってきます。

ただ、git/githubについてはある程度作業をしないと覚えるのは難しいので以前記事で紹介したOSSの翻訳等でプルリクエストを作成して覚えるのがオススメです。

https://zenn.dev/estra/articles/translate-with-gitandgithub

プラグイン開発で最も役立ったのは、他の人が作成したプラグインにプルリクエストを送ってみるというものでした。Obsidianのコミュニティモデレーターの一人であるdeath_au氏が開発したSliding Paneというプラグインに日本人用のスタイル変更機能を実装してプルリクエストをかけ、無事にマージされました。

プルリクエストの際にSliding Paneの構造をみて解析し、自分のほしい機能をなんとか作ってみましたが、これによってプラグインの基本構造を理解することができました。僕が初めて開発したプラグインもSliding Paneと同じ構造、基本システムとなっています。お気に入りのコミュニティプラグインにプルリクエストをかけることでプラグインの基本構造と機能実装を学ぶことができるのかなりオススメです。

開発から公開までのワークフロー

実際にプラグインを初めて開発して公開するまでの一連の流れの概略は以下となります。

流れを見てみると「実際に作ってみる」までにいくつかのハードルがあるのでその部分について説明していきましょう。

今回の第一回目の記事では1~3までを説明していきます。

開発と解析の準備

いきなり開発を行う前にやっておくこと、理解しておくことがいくつかあるので説明してきます。

開発用保管庫とプラグインフォルダ

Obsidianのプラグイン開発や解析を始める前に、まずはプラグインのコードがどこにあるか知っておく必要があります。

まずはプラグイン開発用に保管庫を用意しましょう。
適当にコミュニティプラグインを何個かいれてみてください。

コミュニティプラグインの各ファイルが置いてあるディレクトリは設定画面のコミュニティプラグインのタブを開いて画像のフォルダアイコンをクリックすることで開くことができます。

コミュニティプラグインを一つでもインストールすると
path/vaultFolderName/.obsidian/plugins/ のように保管庫のフォルダ直下にあるObsidianのconfigフォルダにpluginsというフォルダが作成されます。このpluginsフォルダに各プラグインごとにフォルダが作成されてコードがダウンロードされることになります。

実際にフォルダを開いてみるとこんな感じになっています。

プラグインを開発する際には、プラグイン開発用の保管庫の.obsidian/plugins/に開発プラグイン用ディレクトリを作成してデバッグしていきます。

プラグインフォルダに入っているもの

各プラグインフォルダに何がはいっているかというと以下の4つのファイルです。

  1. main.js
    プラグインのメイン処理の部分
  2. styles.css
    プラグイン用のcssファイル
  3. manifest.json
    プラグインのメタ情報ファイル
  4. data.json
    プラグイン設定の保存用に生成されるjsonファイル

プラグインインストール時にはmain.jsmanifest.jsonが必ずインストールされますが、プラグインによってスタイルがないという場合があります。しかし概ねsytles.cssを含めた3つのファイルがプラグイン専用のフォルダに配置されることになります。最後のdata.jsonはプラグインに設定項目がある場合など、設定変更した際の情報などを保存するために生成されます。

逆に、コミュニティプラグインとしてリリースする際には、main.jsmanifest.jsonの2つを必ずリリースとして含め、styles.cssはあれば入れるということになります。

サンプルプラグイン

このセクションではサンプルプラグインのソースコードを読み解き、ビルドして実際に動かしてみるまでの説明を行います。

Obsidianの公式が公開しているサンプルプラグインではプラグインの作成と公開の手順が記載されています。このリポジトリは初めて開発する際には必ず参照してください。

また、プラグイン開発を行う際にはこのプラグインをテンプレートとして開発していくので重要なリポジトリとなっています。

それではまずローカルにcloneしてみましょう。

上で説明した、.obsidian/plugins/のフォルダにこれをgit cloneしてください。cloneしたらvscode等で開いてみてください。

gitをターミナル等から使ったことがない人は、zipファイルをダウンロードして解答してvscodeからフォルダを開くことでみてください。

Readmeを見てみる

まずはReadmeに目を通してみましょう。Readmeにはプラグイン開発の基本的なやり方が記載されています。実はプラグインの基本的なフローについてはここに記載されています。Readmeを日本語訳してみましたので見てみてください。

Readme日本語訳
## サンプルプラグイン

これはObsidianのサンプルプラグインです。

このプロジェクトでは型チェックとドキュメンテーションにTypescirptを利用しています。リポジトリはTypesciprtの定義フォーマット上の最新のプラグインAPI(obsidian.d.ts)に基づいており、APIが何を行っているかを記述するTSDocsコメントを含んでいます。

**ノート:** Obsidian APIは依然としてアーリーアルファであり、常に変更の可能性があることに注意してください。

このサンプルプラグインではプラグインAPIのいくつかの基本的な機能のデモンストレーションを行います。
- `styles.css` を利用してデフォルトスタイルカラーをredに変更
- クリック時に通知を表示するリボンアイコンの追加
- モーダルを開く"Open Sample Modal"コマンドを追加
- 設定ページにプラグイン設定タブを追加
- グローバルclickイベント登録とコンソールへの'click'アウトプット
- 'setInterval'をコンソールに記録するグローバルインターバルでの登録

## プラグイン開発は初めて?

新規プラグイン開発のためのクイックスタートガイド

- 「Use this template」ボタンをクリックしてこのリポジトリをテンプレートとしてコピーしてください
- リポジトリをローカルの開発用フォルダへとクローンしてください。kのフォルダは`.obsidian/plugins/your-plugin-name` folder`に置いておくと開発に便利です。
- NodeJSをインストールして、リポジトリの元で`npm i`コマンドを実行します。
- プラグイン用に`main.ts`から`main.js`へとコンパイルするために`npm run dev`を実行します。
- `main.ts`(または新しく`.ts`ファイルを作成し)へ変更を加えます。これらの変更は自動的に`main.js`へとコンパイルされます。
- Obsidianをリロードしてプラグインの最新バージョンをロードします。
- 設定ウィンドウにてプラグインを有効化してください。
- ObsidianのAPIをアップデートするにはリポジトリフォルダにてコマンドラインから`npm update`を実行してください。


### 新規リリース方法

- `1.0.1`といったバージョン番号と最新リリースに必要な最小のObsidianのバージョン番号に合わせて `manifest.json` をアップデートしてください。
- `version.json` ファイルについては、"プラグインの新規バージョン": "Obsidianの最小バージョン" を追記して、Obsidianの古いバージョンでも互換性のプラグインがダウンロードできるようにアップデートしてください。
- 最新バージョン番号を"Tag version"として使って新しいGithubリリースを作成します。その際にプレフィックスに `v` をつけないで正確なバージョン番号を記載してください。例として次のリンクを確認してください。https://github.com/obsidianmd/obsidian-sample-plugin/releases
- `manifest.json`, `main.js`, `styles.css` の3つのファイルをバイナリファイルとしてアップロード
- リリースを公開します。

### プラグインをコミュニティのプラグインリストに追加する

- 最初のバージョンを公開
- `README.md` ファイルをリポジトリのルートに配置
- https://github.com/obsidianmd/obsidian-releases にプラグインを追加してプルリクエストを作成する

### 使い方

- このリポジトリをclone
- `npm i` または `yarn` で依存関係をインストール
- `npm run dev` でウォッチモードでコンパイルを開始

### 手動インストールの方法

- `main.js`, `styles.css`, `manifest.json`の3つのファイルを保管庫の`VaultFolder/.obsidian/plugins/your-plugin-id/`にコピー&ペーストする。
  

### APIドキュメント

https://github.com/obsidianmd/obsidian-api を確認してください。

ただ、プラグイン開発を初めてやる人にとっては内容的にかなり端折られており、これを見て開発を始めるのは難しい(実際につまずく部分がある)ので、この記事中で足りない部分を補足していきたいと思います。

フォルダ構造を理解する

Readmeを軽く目を透したら、次はフォルダ構造を見てみます。サンプルプラグインをcloneしたディレクトリ配下に以下のようにファイルが配置されてるはずです。

.
├── .gitignore
├── README.md
├── main.ts
├── manifest.json
├── package.json
├── rollup.config.js
├── styles.css
├── tsconfig.json
└── versions.json

プラグイン開発において、まずこれらのファイルがどんな役割を行っているかを知る必要があります。

ファイル名 役割
.gitignore git監視しないアイテムを記述する(ビルドしたmain.jsなど)
README.md コミュニティリリース時の説明ドキュメントとなる
main.ts プラグインのメインプログラムファイルでソースコード
manifest.json プラグインのメタ情報(作者やバージョン情報などを記載)
package.json nodeモジュールの依存やnpmのscriptなどを記載
rollup.config.js Rollup用の設定ファイル
styles.css プラグイン用のスタイル(カスタムCSSと考えれば良い)
tsconfig.json main.ts(Typescript)をmain.js(Javascript)にコンパイルするための設定ファイル
versions.json プラグインのバージョン情報

各ファイルについての概要は上の表のようになります。

プラグインの実際の処理となるソースコード部分はmain.tsstyles.cssの2つが基本となります。

ソースコードはこれらのものとなりますが、実際にプラグインを動かすプログラムはmain.jsということに注意してください。

しかし、サンプルプラグインのファイルを見てみてもどこにもmain.jsがありません。というのもTypescriptでのプログラム作成時には最終的にコンパイルをかけてソースとなるmain.tsからmain.jsファイルを生成する必要があります。このコンパイルは自分自身で行う必要があります。

実際このサンプルプラグインをcloneしただけではサンプルプラグインをそのまま使うことができません。

サンプルプラグインに書いてあるとおり、CLIにてnpm iまたは yarnコマンドを打ってビルドするのに必要な依存関係(node modules)をインストールする必要があります。この部分についてはプラグイン開発で一番面倒なところといってみいいかもしれません。

npmをインストール

このままではサンプルプラグインをビルドして動かすことができないので、まずはnpmというツールをインストールします。

このnpmのインストールについて「多くの記事やサイトで「Node.jsをインストールする」という方法が紹介されていますが、このNode.jsはバージョン変動が激しいのでNode.jsのバージョン管理ツールとしてnodebrewをインストールするという方法が紹介されており、そのnodebrewをインストールするためにHomebrewをインストールするというどんどん一段回上の管理ツールがでてきて、わけが分からなくなります。

僕の場合、npm関連のためだけにObsidianで軽く10個以上のノートを作成するはめになりました。なので管理ツールなどは最低限にして、色々な詳細はすっとばしてnpm iコマンドが打てるところまで行きましょう。

まずはNode.jsの公式ページにいってnodeのダウンロードとインストールを行ってください。

https://nodejs.org/ja/

その後はターミナルを開いて次のコマンドを打ってください。

# npmのグローバルインストール
sudo npm install -g npm
# npmのバージョン確認コマンドでインストールできたか確認
npm -v
# これでバージョン番号がでてくればOK

これでとりあえずOKです。
もし詰まったらnpmでググってください。npmの使い方についても最低限しておき、適宣しらべていけば良いと思います。

ちなみにサンプルプラグインをビルドするのに「npm iまたはyarnコマンドを打つ」という話でしたが、Yarnというのはnpmの代替ツールですのでとりあえずは気にしないで大丈夫です。

npmについてもっと詳しく知りたい方はこちらの動画を参考にしてください。npmの全体像がかなりわかり易く説明されています。

サンプルプラグインをビルド

最低限npmの準備ができたのでターミナルを開いて、サンプルプラグインのディレクトリのトップまで移動してください。プラグインが置いてあるvalutFolderName/.obsidian/plugins/obsidian-sample-plugin/のところです。

移動したら次のコマンドを打ちます。

npm i

このiはinstallのiであって、npm iよって何がおきるかというとでpackage.jsonに記載されている必要なパッケージをnode_modulesというフォルダをプラグインディレクトリに作成し、そこに各パッケージをインストールしてくれます。

このインストールが完了してようやくサンプルプラグインのビルドの準備が終わりました。

それではmain.tsmain.tsにコンパイルするために次のコマンドを打ちます。

npm run dev

このコマンドによってウォッチモードに入り、うまくいくとターミナルの画面が次のようになるはずです。

このモードであればソースコードに変更を加えてもリアルタイムでコンパイルを行ってくれます。デバッグ時にはこのコマンドを使いましょう。このモードを止めるにはTerminal上でCmd+C を押してください。

さて、vscode等でこのディレクトリを開いてみましょう。vscodeを入れておけば次のコマンドでこのディレクトリをvscodeで開くことができます。

code ./

しらないファイルとフォルダがいくつかできていますね。まずはnode_modulesですが、これはnpmでインストールしたパッケージ類のためのフォルダです。中を簡単にみてみると、ずらっと色々なフォルダがあり、Obsidianという名前のフォルダもあることがわかります。あとで説明しますがこのフォルダの中にObsidianのAPIモジュール(obsidina.d.ts)が入っています。

次にpakage-lock.jsonですが、これはnpm iによって生成されたファイルです。実際にインストールされたパッケージ情報が記載されています。とりあえずのところは気にしなくても大丈夫です。

そしてmain.jsですが、これがソースコードたるmain.tsから上記のnode_modulesに入っている様々なパッケージから必要なものなどをぶちこんで作り上げたJavascriptファイルとなります。npm run devコマンドによって作られました。

さて、コンパイルが終わったのでサンプルプラグインが使えるようになっているはずです。

設定からコミュニティプラグインタブを開いて「プラグインの再読み込み」を行ってください。

これでSample Pluginが有効化できるようになったはずです。画面をスクロールして有効化ボタンをおしましょう。有効化して設定画面の左側の文字色が下のように赤になれば成功です。

サンプルプラグインでできることはReadmeに書いてあるとおり

  • デフォルトカラーの変更
  • 左サイドバーのリボンにクリックすると通知するボタンを追加
  • モーダルを開くコマンドOpen Sample Modalの追加
  • 設定ページにプラグイン用の設定タブを追加
  • コンソールへのイベント通知

などです。実際に触ってみてください。

次の記事ではサンプルプラグインの構造について説明していきたいと思います。

↓次回

https://zenn.dev/estra/articles/obsidian-dev-plugin_2

Discussion

ログインするとコメントできます