1 Obidian 开发

Obsidian 基于 Electron 框架开发（开发者可以使用 Web 技术构建桌面应用，Google 的 Flutter 也是类似的框架），主要使用 HTML、CSS 和 JavaScript。后端则依赖 Node.js（Node.js 是基于 Chrome V8 引擎的 JavaScript 运行环境），使 JavaScript 能在服务器端运行。

开发 Obsidian 插件时，需要掌握 JavaScript 和 Node.js。比如，利用 Node.js 提供的模块和 API 进行文件操作、访问系统资源、处理网络请求等。

2 开发环境

我的开发环境是：VSCode + Node Docker + Copilot。这样不仅不会影响我的宿主机环境，开发起来也很舒适，还可以利用辅助编码工具。

如果想开发 Obsidian 插件，就需要安装 Node.js 环境。Node.js 提供了 JavaScript 的运行环境和许多内置模块；同时，安装 Node.js 也会安装 npm，用于管理插件项目的依赖项。

推荐使用 Node.js 的第 18 版：

1
2
$ docker run --name obdev --rm -v /exports:/exports -it node:18 sh
$ npm -v # 8.19.4

我使用了 VSCode + Copilot，这样一来就不再需要频繁搜索各种代码用法，只需提供简单的文本描述即可自动生成代码。一旦环境搭建完成，编程过程就像写作文一样。现在看来，陌生技术已不再是难题，90% 的时间都可用于处理业务逻辑。

3 最简单示例

3.1 创建插件

三方插件至少需要以下三个文件：main.js、manifest.json 和 styles.css。

官方提供的示例代码 obsidian-sample-plugin 是一个很好的起点，只需对其进行略微修改，就可以实现自己的插件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
git clone https://github.com/obsidianmd/obsidian-sample-plugin
cd obsidian-sample-plugin
# 进入 docker 开发环境
npm install
npm run dev # 开启热编译模式，修改时自动编译

# 此时编译出 main.js
# 将上述三个文件复制到 obsidian plugins 目录

cd obroot/.obsidian/plugins/
mkdir obsidian-sample-plugin
cp x/main.js x/manifest.json x/styles.css obsidian-sample-plugin/

# 也可选择把代码放在 .obsidian/plugins下，或使用链接，这样不需要每次复制

重启 Obsidian 后，将在已安装的第三方插件列表中看到“Sample Plugin”，只需启用它即可。

在示例代码中可以看到一些 TypeScript 脚本。Node.js 不能直接运行 TypeScript 文件，需要使用编译器将 TypeScript 文件编译成 JavaScript 文件后再运行。在 package.json 文件中可以看到 tsc 的编译过程。

TypeScript 是 JavaScript 的一个超集（不仅具备 JavaScript 的所有特性和语法，还添加了静态类型系统等新功能）。此外，也可以使用 React、Vue 或 Svelte 来开发插件。

3.2 主要文件说明

  • main.js # 编译后的程序
  • styles.css # 样式
  • manifest.json # 插件信息
  • main.ts # 程序入口 typescript
  • package.json # 配置管理文件
  • versions.json # 版本信息

3.3 修改插件

3.3.1 manifest.json

  • 修改唯一标识 id
  • 修改插件名 name

3.4 重新加载插件

由于在编译环境中已设置 npm run dev 以进行热编译，因此每当程序修改并保存后，就会立即编译成 main.js。

在 Obsidian 的设置中，可以通过禁用并重新启用插件来重新加载它，以便使用修改后的功能。需要注意的是，有时在禁用和重新启用过程中，原有的设置可能会丢失。

3.5 插件安装

传统方法参见：DataView 的插件安装方法

1
2
git clone git@github.com:blacksmithgu/obsidian-dataview.git
ls scripts/*

新方法参见：github自动编译Release版本

4 版本升级

在进行版本升级时，请确保修改以下内容：

  • 更新 manifest.json 文件。
  • 更新 versions.json 文件。
  • 更新 CHANGELOG.md 以记录更改和新增功能。
  • 创建新的标签（tag）。
  • 在 GitHub Release 中更新新版描述信息。

5 常用功能

以下是我们常用的一些插件功能：

  • 使用 Ctrl+P 命令快速调用功能
  • 弹出对话框或提示框界面
  • 定时执行特定任务，例如同步、上传和下载
  • 在特定位置显示更多信息或界面，如图标、提示、选项卡和侧边栏
  • 修改 Markdown 文档的内容
  • 读写设置信息并显示设置界面

6 README

介绍文本展示在“第三方插件”->“社区插件市场”中。当点击具体插件时，右侧会显示其内容。通常是加载插件源码中 README.md 文件的内容。

详见：README_写法

注意：README 里最好写绝对路径，以方便在 Obsidian 界面中跳转，如：https://github.com/mokeyish/obsidian-enhancing-export/

7 上传社区插件市场

详见：Obsidian_上传社区

8 注意事项

8.1 发布前需要检查

  • 代码放 src 下面
  • 设置界面：不要使用 Setting, General，以及工具名作为一层标题，也不能没有一级标题
  • 多语言支持：英文字符串都用 Sentence 方式：Extract Tags->Extract tags
  • README
  • 清除 console.log
  • 如果使用 action 自动编译，基本得把所有 warning 全部改掉，保证：
    • npm run dev 正常
    • npm run build 正常
  • Ctrl+P 命令的 id 和 name 都不要加自己工具名的前缀
  • 没用的代码不要加，比如重写了，但是没改内容的函数
  • http 请求不要用 fetch，而用 obsidian 提供的 requestURL，注意参数格式不同，传文件尤其不一样
  • 不要用 node.js 中的方法，否则就不能在手机端使用 import * as fs from 'fs';
  • 仓库名最好不要出现在文件名中，他认为分仓库不会重名
  • 要用 async/await 取代 then...catch 格式

8.2 设计技巧

  • 安全防范：删除前提醒用户，失败提醒用户
  • 节约 token，明确告知，尤其是处理文本较长时
  • 加捐赠功能
  • 一些小 tips
    • tab 补全
    • 提示框
    • 记下用户操作
    • 善用快捷链
    • 善用 cMenu 快捷按钮

9 参考资源

9.1 帮助文档

https://docs.obsidian.md/Home

更为推荐的方法是：直接到 node_modules/obsidian/中看源码

9.2 api 详解

https://github.com/obsidianmd/obsidian-api

该项目详细阐述了如何编写各特定文件。

9.3 中文文档

https://luhaifeng666.github.io/obsidian-plugin-docs-zh/

强烈推荐这个中文文档，它包含了 Obsidian 插件常用的控件方法，并配有示例，只需复制即可使用。此外，这个帮助文档本身也是一个开源项目，之前大家可以参与编辑和提交。

9.4 发布

  • 整体示例：https://github.com/obsidianmd/obsidian-sample-plugin
  • 发布流程：https://docs.obsidian.md/Plugins/Releasing/Submit+your+plugin