tadashi-aikawa / obsidian-tempura

Obsidian Tempura

Note The logo above was created by DALL-E3

Note This repository is still pre-alpha version.

Required

• Obsidian
• Templater

API Documantation

https://tadashi-aikawa.github.io/obsidian-tempura/

2種類の使い方

Obsidian Tempuraには2種類の使い方があります。

1. Script User Functionsとして使う
2. Templater scriptの統合開発環境として使う

それぞれ、インストールの仕方や利用方法が異なります。

Script User Functionsを使う場合

普通の使い方です。

インストール

fryTempura.jsを取得してscript files folder locationで指定されたパスの配下に配置するだけです。

fryTempura.jsは以下のURLから取得できます。

https://raw.githubusercontent.com/tadashi-aikawa/obsidian-tempura/main/lib/fryTempura.js

使い方

tp.user.fryTempura()からObsidian Tempuraの関数群を利用できます。const T = tp.user.fryTempura() で宣言したTを利用してください。

<%*
const T = tp.user.fryTempura()

T.insert("🦉Mimizou")
%>

Warning 上記以外の書き方をすると、TypeScriptとしては問題なくても、tsファイルからmdファイルへの変換で動かなくなる可能性があります。

利用できる関数の定義はAPI Documentationをご覧ください。

Templater scriptの統合開発環境として使う場合

以下のことができます。

• IDEによる型チェック/推論
• IDEによるオートコンプリート
• TypeScriptファイルをTemplater script(markdownファイル)に変換
• ホットリロード

バージョン管理やIDEでの開発を好むTypeScript/JavaScript開発者の方にオススメです。

Windows/Ubuntu環境で、Node.js v18の動作を確認しています。

インストール

npm install https://github.com/tadashi-aikawa/obsidian-tempura.git
npx tempura init

アップデートしたいときは

2023-11-19以後のものをバージョンアップする場合は以下のコマンドを実行します。

npx tempura update

2023-11-19以前のものをバージョンする場合は、updateコマンドがないため以下の手順が必要です。

npm update obsidian-tempura && npm install obsidian-tempura
npm install -D typescript@5.2 @tsconfig/node18 chokidar@3 @babel/core@7 @babel/plugin-transform-typescript@7 obsidian@^1.4.11

設定

tempura initで作成されるconfig.jsonは以下です。

{
  // TemplaterのScriptフォルダのパス
  // "script"を指定した場合、カレントディレクトリの`./script`以下に最新のスクリプト(jsファイル)が転送される
  "scriptFilesFolderLocation": "script",
  // tsファイルのディレクトリをキーに、mdファイル(Templater Script)のディレクトリパスを値に設定
  // "src": "dist"を指定した場合、カレントディレクトリの`src`配下にあるtsファイルがmdファイルに変換され、カレントディレクトリの`dist`配下に転送される
  "deployMap": {
    "src": "dist"
  }
}

実際に利用する際は、Vaultの設定にあわせてconfig.jsonの設定を変更しましょう。以下は具体例です。

{
  "scriptFilesFolderLocation": "/home/tadashi-aikawa/vaults/minerva/templater/scripts",
  "deployMap": {
    "common": "/home/tadashi-aikawa/vaults/minerva/templater",
    "home": "/home/tadashi-aikawa/vaults/minerva/templater",
  }
}

deployMapのcommonとhomeが同じ設定値になっていますが、これはどちらの成果物も同じディレクトリ内部に転送されることを意味します。Obsidian Tempuraはファイル同期はしないため、deployMapの値に指定されたディレクトリのファイルが削除されることはありません。(ただし、同名ファイルは上書きされます)

ビルド

以下のコマンドを実行すると、tsファイルに変更があった場合に自動でビルドして転送します。

npx tempura

トリプルスラッシュの扱い

トリプルスラッシュ (///) でコメントアウトされたコードは、そのままコメント解除されます。たとえば、以下のコードをtsファイルとして書いた場合

///<%*
// begin
const T = tp.user.fryTempura();
T.notify("hoge")
// end
///%>

以下のようにビルドされます。

<%*
// begin
const T = tp.user.fryTempura();
T.notify("hoge")
// end
%>

これはTemplater tagsを指定するユースケースでの利用を想定しています。

early returnの書き方

early returnの書き方は少し特殊であり、マクロのようなルールがあります。early returnさせるには、以下のように引数なしでT.exit()の値をthrowしてください。

const T = tp.user.fryTempura(); // Tにバインドする定義も必須です
throw T.exit();

このコードはビルド時に以下のように変換されます。

return

もう少し実用的なサンプルコードは以下です。

///<%*
const T = tp.user.fryTempura();
const props = T.getProperties();
if (!props) {
  throw T.exit();
}

T.notify(JSON.stringify(props));
///%>

これは以下のmdファイルに変換されます。

<%*
const T = tp.user.fryTempura();
const props = T.getProperties();
if (!props) {
  return
}
T.notify(JSON.stringify(props));
%>

例外処理の書き方

例外処理の書き方は少し特殊であり、マクロのようなルールがあります。処理の中断が必要な例外を発生させるには、以下のように引数ありでT.exit()の値をthrowしてください。

const T = tp.user.fryTempura(); // Tにバインドする定義も必須です
throw T.exit("プロパティが存在しません");

このコードはビルド時に以下のように変換されます。

T.notify("プロパティが存在しません"); return

もう少し実用的なサンプルコードは以下です。

///<%*
const T = tp.user.fryTempura();
const props = T.getProperties();
if (!props) {
  throw T.exit("プロパティが存在しません");
}

T.notify(JSON.stringify(props));
///%>

これは以下のmdファイルに変換されます。

<%*
const T = tp.user.fryTempura();
const props = T.getProperties();
if (!props) {
  T.notify("プロパティが存在しません"); return
}
T.notify(JSON.stringify(props));
%>

ベータ版への道

• tsファイルに型を記載できるようにする
  • noImplicitAnyのオプションを削除
• 既存Templater Scriptsを移行しながら不足しているfunctionsを補っていく
• functionsのインターフェース整理
• docsの整理

🤖 開発者むけ

Required

• Bun (v1.0.8 >=)

Provisioning

bun install

Build

bun run build

Artifacts

• lib/fryTempura.js

Build docs

bun run build:docs

Artifacts

• docs