Obsidian插件开发

1 Obidian 开发

Obsidian 基于 Electron 框架开发，其前端主要使用了 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 镜像，这次就直接使用了：

1
2
3

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

3 最简单示例

3.1 创建插件

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

官方推荐从最简单的示例代码开始，略做修改即可实现自己的插件：

# git clone https://github.com/obsidianmd/obsidian-sample-plugin
# cd obsidian-sample-plugin
# npm install
# npm run dev # 开启热编译模式，修改时自动编译

此时编译出 main.js
将上述三个文件复制到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 的一个超集（一个集合包含另一个集合的所有元素，还包含额外的元素），TypeScript 包含了 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 来进行热编译，所以一旦程序修改保存，就会立即编译成 js。

在 Obsidian 的设置中，你可以通过禁用再启用该插件来重新加载它，以使用修改的功能；需要注意的是：每次禁用再启用设置都会丢失原有设置。

3.5 插件安装

旧方法参见：DataView 的插件安装方法

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

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

4 常用功能

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

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

5 README

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

详见：README写法

6 上传社区插件市场

详见：Obsidian_上传社区

7 使用体会

我使用了 VSCode+Copilot，这样就不再需要搜索各种代码用法，只需提供简单文本描述来自动生成代码。

可能你觉得我说得有些夸张，但一旦环境搭建好，编程就和写作文差不多。目前看来，陌生的技术已经不再是难题，90% 的时间都用于业务逻辑的处理。

8 参考资源

8.1 帮助文档

https://docs.obsidian.md/Home

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

8.2 api 详解

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

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

8.3 中文文档

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

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

8.4 官方文档

https://docs.obsidian.md/Home

8.5 发布

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