siyuan-note / plugin-sample

SiYuan plugin sample

中文

SiYuan plugin sample

Get started

• Make a copy of this repo as a template with the Use this template button, please note that the repo name must be the same as the plugin name, the default branch must be main
• Clone your repo to a local development folder. For convenience, you can place this folder in your {workspace}/data/plugins/ folder
• Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder
• Execute pnpm run dev for real-time compilation
• Open SiYuan marketplace and enable plugin in downloaded tab

Development

• i18n/*
• icon.png (160*160)
• index.css
• index.js
• plugin.json
• preview.png (1024*768)
• README*.md
• Fontend API
• Backend API

I18n

In terms of internationalization, our main consideration is to support multiple languages. Specifically, we need to complete the following tasks:

• Meta information about the plugin itself, such as plugin description and readme
  • description and readme fields in plugin.json, and the corresponding README*.md file
• Text used in the plugin, such as button text and tooltips
  • src/i18n/*.json language configuration files
  • Use this.i18.key to get the text in the code
• Finally, declare the language supported by the plugin in the i18n field in plugin.json

It is recommended that the plugin supports at least English and Simplified Chinese, so that more people can use it more conveniently.

plugin.json

{
  "name": "plugin-sample",
  "author": "Vanessa",
  "url": "https://github.com/siyuan-note/plugin-sample",
  "version": "0.1.3",
  "minAppVersion": "2.8.8",
  "backends": ["windows", "linux", "darwin"],
  "frontends": ["desktop"],
  "displayName": {
    "default": "Plugin Sample",
    "zh_CN": "插件示例"
  },
  "description": {
    "default": "This is a plugin sample",
    "zh_CN": "这是一个插件示例"
  },
  "readme": {
    "default": "README.md",
    "zh_CN": "README_zh_CN.md"
  },
  "funding": {
    "openCollective": "",
    "patreon": "",
    "github": "",
    "custom": [
      "https://ld246.com/sponsor"
    ]
  },
  "keywords": [
    "sample", "示例"
  ]
}

• name: Plugin name, must be the same as the repo name, and must be unique globally (no duplicate plugin names in the marketplace)
• author: Plugin author name
• url: Plugin repo URL
• version: Plugin version number, it is recommended to follow the semver specification
• minAppVersion: Minimum version number of SiYuan required to use this plugin
• backends: Backend environment required by the plugin, optional values are windows, linux, darwin, docker, android, ios and all
  • windows: Windows desktop
  • linux: Linux desktop
  • darwin: macOS desktop
  • docker: Docker
  • android: Android APP
  • ios: iOS APP
  • all: All environments
• frontends: Frontend environment required by the plugin, optional values are desktop, desktop-window, mobile, browser-desktop, browser-mobile and all
  • desktop: Desktop
  • desktop-window: Desktop window converted from tab
  • mobile: Mobile APP
  • browser-desktop: Desktop browser
  • browser-mobile: Mobile browser
  • all: All environments
• displayName: Template display name, mainly used for display in the marketplace list, supports multiple languages
  • default: Default language, must exist
  • zh_CN, en_US and other languages: optional, it is recommended to provide at least Chinese and English
• description: Plugin description, mainly used for display in the marketplace list, supports multiple languages
  • default: Default language, must exist
  • zh_CN, en_US and other languages: optional, it is recommended to provide at least Chinese and English
• readme: readme file name, mainly used to display in the marketplace details page, supports multiple languages
  • default: Default language, must exist
  • zh_CN, en_US and other languages: optional, it is recommended to provide at least Chinese and English
• funding: Plugin sponsorship information
  • openCollective: Open Collective name
  • patreon: Patreon name
  • github: GitHub login name
  • custom: Custom sponsorship link list
• keywords: Search keyword list, used for marketplace search function

Package

No matter which method is used to compile and package, we finally need to generate a package.zip, which contains at least the following files:

• i18n/*
• icon.png (160*160)
• index.css
• index.js
• plugin.json
• preview.png (1024*768)
• README*.md

List on the marketplace

• pnpm run build to generate package.zip
• Create a new GitHub release using your new version number as the "Tag version". See here for an example: https://github.com/siyuan-note/plugin-sample/releases
• Upload the file package.zip as binary attachments
• Publish the release

If it is the first release, please create a pull request to the Community Bazaar repository and modify the plugins.json file in it. This file is the index of all community plugin repositories, the format is:

{
  "repos": [
    "username/reponame"
  ]
}

After the PR is merged, the bazaar will automatically update the index and deploy through GitHub Actions. When releasing a new version of the plugin in the future, you only need to follow the above steps to create a new release, and you don't need to PR the community bazaar repo.

Under normal circumstances, the community bazaar repo will automatically update the index and deploy every hour, and you can check the deployment status at https://github.com/siyuan-note/bazaar/actions.

Developer's Guide

Developers need to pay attention to the following specifications.

1. File Reading and Writing Specifications

If plugins or external extensions require direct reading or writing of files under the data directory, please use the kernel API to achieve this. Do not call fs or other electron or nodejs APIs directly, as it may result in data loss during synchronization and cause damage to cloud data.

Related APIs can be found at: /api/file/* (e.g., /api/file/getFile).

2. Daily Note Attribute Specifications

When creating a daily note in SiYuan, a custom-dailynote-yyyymmdd attribute will be automatically added to the document to distinguish it from regular documents.

For more details, please refer to Github Issue #9807.

Developers should pay attention to the following when developing the functionality to manually create Daily Notes:

• If /api/filetree/createDailyNote is called to create a daily note, the attribute will be automatically added to the document, and developers do not need to handle it separately
• If a document is created manually by developer's code (e.g., using the createDocWithMd API to create a daily note), please manually add this attribute to the document

plugin-sample's Issues

插件模板缺少添加插件按钮到块菜单和toolbar

plugin.json 的 frontends 可以增加一个 tablet 或 pad 选项吗？

如题，毕竟安卓手机和安卓平板的UI完全不是一回事。

关于插件名称的疑惑

文档说：

通过 Use this template 按钮将该库文件复制到你自己的库中，请注意库名必须和插件名称一致

1. 这里的插件名指的是 plugin.json 的 name 字段吗？
2. github 的 repo 名称必须和 name 保持一致？
3. 那也就是说，插件名必须是英文，不能为中文？

---

如果插件名必须为英文的话，那我觉得有点不妥。

模板使用问题

clone模板，pnpm i后，会显示异常，似乎是会去使用node_modules下的siyuan.d.ts而不是src下的

如果客户端语言不是中文也不是英语，是默认用 en_US.json 吗？

must i statically assign the API token so to use the APIs?

可否额外支持 vite 打包

原来的插件系统也是 vite 打包的，如果新的系统也可以 vite 的话迁移起来会容易很多。

去掉 package 中 siyuan 依赖

既然后续的插件开发使用的接口直接定义在 siyuan.d.ts 当中，那 package.json 中的 siyuan@latest 依赖是不是可以去掉了？

插件系统能够热更新吗

使用webpack直接输出到plugins文件夹内，思源能够实现检测文件变化，并且重新加载插件吗。

我现在是每生成一次都重启一次思源。

是否可以有一个单独热更新当前插件的功能