Obsidianプラグインの作り方 - あるSEのつぶやき・改

はじめに

Obsidian プラグインの作り方を、備忘録として残しておきます。

今までに作成した Obsidian プラグインは、以下になります。

はじめに
開発環境
プラグインを開発する
GitHub Actions でビルドを実行する
プラグインを申請する
プラグインのアップデート
おわりに

開発環境

Obsidian プラグインの開発には、以下が必要です。

Visual Studio Code
Node.js
TypeScript

開発用の Vault を作成します。ここでは、plugins という Vault 名にします。

Obsidian の表示言語を English に変更します。

現時点では、レビュアーの方もユーザーも英語を使っているようなので合わせます。

必要なリポジトリを git clone します。

$ cd plugins/.obsidian/plugins
$ git clone https://github.com/pjeby/hot-reload
$ git clone https://github.com/obsidianmd/obsidian-sample-plugin

hot-reload は Obsidian プラグイン開発専用プラグインで、プラグインの修正をすぐに Obsidian に反映します。

ただし、hot-reload はプラグインとして公開されていないため git clone で取得する必要があります。

obsidian-sample-plugin は、Obsidian プラグインのテンプレートです。

テンプレートを開発するプラグイン名に変更します。ここでは、 media-sync とします。

$ mv obsidian-sample-plugin media-sync

manifest.json を、自分が開発するプラグインの内容に書き換えます。

以下は Media Sync の例ですが、適宜書き換えてください。

{
    "id": "media-sync",
    "name": "Media Sync",
    "version": "0.0.1",
    "minAppVersion": "0.0.0",
    "description": "Downloads media files(eg. images, PDFs) from the URLs in documents and displays the content.",
    "author": "fnya",
    "authorUrl": "https://github.com/fnya",
    "isDesktopOnly": true
}

isDesktopOnly のデフォルトは false で、このままだとパソコンとモバイルの両方で動作するプラグインとなります。パソコンに限定したい場合は isDesktopOnly を true にします。

package.json の必要箇所を修正します。

以下は Mesia Sync の例です。

{
    "name": "media-sync",
    "version": "0.0.1",
    "description": "Downloads media files(eg. images, PDFs) from the URLs in documents and displays the content.",
    "author": "fnya",
    "license": "MIT",
    "repository": {
        "type": "git",
        "url": "git+https://github.com/fnya/media-sync.git"
    },
}

プラグインに必要なライブラリをインストール後、起動します。

$ cd media-sync
$ npm install
$ npm run dev

Obsian で、Community plugins を有効にした後で、Hot Reload と Media Sync を有効にします。

これで開発環境が整いました。

プラグインを開発する

実際のプラグイン開発は、下記の公式ドキュメントやフォーラムを参照しながら行います。

アイコンを使用する場合は、以下で使用可能なアイコンを調べることができます。

Lucide | Lucide

GitHub Actions でビルドを実行する

.github/workflows/release.yml を作成することで、GitHub でタグ作成時にビルドを実行できるようになります。

name: Release Obsidian plugin

on:
  push:
    tags:
      - "*"

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18.x"

      - name: Build plugin
        run: |
          npm install
          npm run build

      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          tag="${GITHUB_REF#refs/tags/}"

          gh release create "$tag" \
            --title="$tag" \
            --draft \
            main.js manifest.json styles.css

GitHub Actions を実行するには、リポジトリで GitHub Actions に Read and write permissions の権限を付与する必要があります。

GitHub Actions 実行後に、リリースの Draft が自動で作成されます。

Draft のリリースを、Publish release することでリリースを作成します。

リリースに含まれる main.js, manifest.json, style.css がプラグイン申請時に必要な情報となります(style.css はオプション)。

プラグインを申請する

Obsidian プラグインの申請は、下記ドキュメントに従っていれば基本的に問題ありません。

Submit your plugin - Developer Documentation

以下に概要を記載します。

申請前に、下記の条件が満たされているか確認します。

GitHub のリポジトリで、下記ファイルが含まれていること
- README.md
- LICENSE
- manifest.json
GitHub で下記ファイルを含むリリースが作成されていること
- main.js
- manifest.json
- styles.css (オプション)

README.md には、機能だけでなく操作方法の説明も必要です。README.md がユーザーに公開される説明になるためです。

community-plugins.json を編集して、プラグイン申請の Pull request を作成します。

ドキュメントにあるように、申請内容を追記します。

{
  "id": "doggo-dictation",
  "name": "Doggo Dictation",
  "author": "John Dolittle",
  "description": "Transcribes dog speech into notes.",
  "repo": "drdolittle/doggo-dictation"
}