massivebox/siyuan-jsdraw-plugin
massivebox/siyuan-jsdraw-plugin
2
1
Fork 0
forked from mirrors/plugin-sample-vite-svelte
Code Issues 5 Pull requests Projects 3 Releases 7 Packages Wiki Activity Actions

README

Browse source
This commit is contained in:
frostime 2023-05-19 21:24:51 +08:00
parent 86fc5b3595
commit ba8e431dec
4 changed files with 171 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -1,6 +1,8 @@
# SiYuan plugin sample with vite and svelte # SiYuan plugin sample with vite and svelte
[中文版](./README_zh_CN.md)
1. Using vite for packaging 1. Using vite for packaging
2. Use soft linking instead of putting the project into the plugins directory program development 2. Use soft linking instead of putting the project into the plugins directory program development
3. Built-in support for the svelte framework 3. Built-in support for the svelte framework
@ -9,30 +11,30 @@
## Get started ## Get started
1. 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 1. 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`
2. Clone your repo to a local development folder at any place 2. Clone your repo to a local development folder at any place
- Notice: we **don't recommand** you to place the folder under your {workspace}/data/plugins/ folder. - Notice: we **don't recommand** you to place the folder under your `{workspace}/data/plugins/` folder.
3. Create development soft links 3. Create development soft links
- It is recommended to create a symbolic link between your development directory and the plugins directory. - It is recommended to create a symbolic link between your development directory and the plugins directory.
- If you have python environment in you device, run the command `python scripts/make_dev_link.py <plugin_dir>` script, `<plugin_dir>` is the absolute path to the plugins directory, e.g. - If you have python environment in you device, run the command `python scripts/make_dev_link.py <plugin_dir>`, `<plugin_dir>` is the absolute path to the plugins directory, e.g.
```powershell ```powershell
>>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins" >>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins"
Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample
``` ```
- You may need to run it as administration, normal windows users can first open the command line as administrator and then run it. Or if you have scoop installed in you windows system, you install `scoop install sudo` and run with sudo. - You may need to run it as administration, normal windows users can first open the command line as administrator and then run it. Or if you have scoop installed in you windows system, you install `scoop install sudo` and run with sudo.
- If you haven't installed python in your environment, you can also manually make a soft link, reference to [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink) - If you haven't installed python in your environment, you can also manually make a soft link
- Create directory `dev` in you workspace
- Window user use [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink); and unix user use ln command
- Notice: make sure that the name of soft link is same as the name in your plugin.json - Notice: make sure that the name of soft link is same as the name in your plugin.json
- As the generated softlink is the same as the plugin name, **do not put the project directory under plugins** (this is contrary to the webpack version) - As the generated softlink is the same as the plugin name, **do not put the project directory under plugins** (this is contrary to the webpack version)
4. Develope 4. Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder
5. Execute pnpm run dev for real-time compilation
- Install NodeJS and pnpm, then run pnpm i in the command line under your repo folder 6. Open SiYuan marketplace and enable plugin in downloaded tab
- Execute pnpm run dev for real-time compilation
- Open SiYuan marketplace and enable plugin in downloaded tab
## I18n ## I18n

72
README_en_US.md
View file

@ -1,72 +0,0 @@
This plugin is a community third-party plug-in development template, in addition to the official development template provides a basic level of functionality, has the following features:
1. based on vite package project, support for hot-loading, in dev mode whether the code or i18n changes can be automatically tracked
2. soft linking instead of putting the project into the plugins directory program development, you can feel free to develop multiple projects in the same workspace at the same time, and do not worry about accidentally deleting the project code in the source
3. built-in support for the svelte framework, compared to react, vue and other virtual DOM-based solutions, svelte such compiled framework is more suitable for plug-in development of such lightweight scenarios
4. provides a github action template to automatically generate package.zip and upload to new release
5. pre-packaged siyuan.d.ts module, no need to manually replace the siyuan module under the node_module
6. Provide with api.ts and sy-dtype.d.ts
## Template usage
1. Use Template
2. Clone to local
3. Create development soft links
- Create the dev directory
- Run the ``scripts/make_dev_link.py`` script, passing in the absolute path to the plugins directory, e.g.
```powershell
>> sudo python . \scripts\make_dev_link.py H:\temporary folder\SiYuanDevSpace\data\plugins
Folder already exists, exit
```
- You may need sudo to run it, I installed sudo myself on windows via scoop and can run it directly that way, normal windows users can first open the command line as administrator and then run it.
- If you haven't installed python in your environment, you can also manually make a soft link, reference to [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink)
- Notice: make sure that the name of soft link is same as the name in your plugin.json
- As the generated softlink is the same as the plugin name, do not put the project directory under plugins (this is contrary to the official template)
4. development
- When pnpm dev mode is enabled, the code and i18n README plugin.json are automatically tracked and the compiled results are placed in the dev directory
- The new version of SiYuan already allows soft links, so there is no need to put the project under plugin.
5. manual release (You can use github action instead)
- pnpm build, automatically generates package.zip
## Github action
The github action is included and can be automatically packaged and published:
1. set the project `https://github.com/OWNER/REPO/settings/actions` page down to **Workflow Permissions** and open the configuration
![](asset/action.png)
2. when you need to release a version, push a tag in the format `v*` and github will automatically release (including package.zip)
3. use conservative pre-release by default, if you don't think this is necessary, change the settings in release.yml to
```yaml
- name: Release
uses: ncipollo/release-action@v1
with.
allowUpdates: true
artifactErrorsFailBuild: true
artifacts: 'package.zip'
token: ${{ secrets.GITHUB_TOKEN }}
prerelease: true # change this to false
```
## Dependencies
This item was modified from [terwer/siyuan-plugin-importer](https://github.com/terwer/siyuan-plugin-importer)
*** Translated with www.DeepL.com/Translator (free version) ***

158
README_zh_CN.md Normal file
View file

@ -0,0 +1,158 @@
[English](./README.md)
# 使用 vite + svelte 的思源笔记插件示例
1. 使用 vite 打包
2. 使用软链接、而不是把项目放到插件目录下的模式进行开发
3. 内置对 svelte 框架的支持
4. 提供一个github action 模板，能自动生成package.zip并上传到新版本中
## 开始
1. 通过 <kbd>Use this template</kbd> 按钮将该库文件复制到你自己的库中，请注意库名必须和插件名称一致，默认分支必须为 `main`
2. 将你的库克隆到本地开发文件夹中
* 注意: 同 `plugin-sample` 不同, 本样例并不推荐直接把代码下载到 `{workspace}/data/plugins/`
3. 创建开发需要的软链接
- 推荐使用软链接来链接你的工作目录和插件目录
- 如果你的设备安装了 python 环境，运行 `python scripts/make_dev_link.py <plugin_dir>` 命令，`<plugin_dir>`是插件目录的绝对路径，示例:
```powershell
>>> sudo python . \scripts\make_dev_link.py "H:\SiYuanDevSpace\data\plugins"
Symlink created: H:\SiYuanDevSpace\data\plugins\plugin-sample
```
- 可能需要使用管理员身份来运行这个命令。对 windows 用户来讲可以首先使用管理员身份打开控制台，然后再运行脚本。如果你的 windows 设备上安装了 scoop 等软件，可以安装 `scoop install sudo` 然后使用 sudo 命令来运行上面的程序
- 如果您的开发环境下没有安装 python，也可以自己手动创建软链接
- 首先手动在工作目录下创建 dev 目录
- windows 用户请使用 [mklink](https://learn.microsoft.com/windows-server/administration/windows-commands/mklink) 命令; unix 用户使用 ln 命令
- 注意：要确保软链接的名称和 plugin.json 中的 name 字段保持一致
由于生成的软链接和 plugin name 相同，所以不要把工程目录放在 plugins 下（这一点和 plugin-sample 模板相反）
4. 安装 [NodeJS](https://nodejs.org/en/download) 和 [pnpm](https://pnpm.io/installation)，然后在开发文件夹下执行 `pnpm i`
5. 执行 `pnpm run dev` 进行实时编译
6. 在思源中打开集市并在下载选项卡中启用插件
## 国际化
国际化方面我们主要考虑的是支持多语言，具体需要完成以下工作：
* 插件自身的元信息，比如插件描述和自述文件
* plugin.json 中的 `description` 和 `readme` 字段，以及对应的 README*.md 文件
* 插件中使用的文本，比如按钮文字和提示信息
* src/i18n/*.json 语言配置文件
* 代码中使用 `this.i18.key` 获取文本
* 最后在 plugin.json 中的 `i18n` 字段中声明该插件支持的语言
建议插件至少支持英文和简体中文，这样可以方便更多人使用。
## plugin.json
```json
{
"name": "plugin-sample-vite-svelte",
"author": "frostime",
"url": "https://github.com/siyuan-note/plugin-sample-vite-svelte",
"version": "1.0.0",
"displayName": {
"en_US": "Plugin sample with vite and svelte",
"zh_CN": "插件样例 vite + svelte 版"
},
"description": {
"en_US": "SiYuan plugin sample with vite and svelte",
"zh_CN": "使用 vite 和 svelte 开发的思源插件样例"
},
"readme": {
"en_US": "README_en_US.md",
"zh_CN": "README.md"
},
"i18n": [
"en_US",
"zh_CN"
],
"funding": {
"custom": [
"https://afdian.net/a/frostime"
]
}
}
```
* `name`：插件名称，必须和库名一致，且全局唯一（集市中不能有重名插件）
* `author`：插件作者名
* `url`：插件仓库地址
* `version`：插件版本号，建议遵循 [semver](https://semver.org/lang/zh-CN/) 规范
* `displayName`：模板显示名称，主要用于模板集市列表中显示，支持多语言
* `default`：默认语言，必须存在
* `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文
* `description`：插件描述，主要用于插件集市列表中显示，支持多语言
* `default`：默认语言，必须存在
* `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文
* `readme`：自述文件名，主要用于插件集市详情页中显示，支持多语言
* `default`：默认语言，必须存在
* `zh_CN`、`en_US` 等其他语言：可选，建议至少提供中文和英文
* `i18n`：插件支持的语言列表
* `funding`：插件赞助信息
* `openCollective`：Open Collective 名称
* `patreon`：Patreon 名称
* `github`：GitHub 登录名
* `custom`：自定义赞助链接列表
## 打包
无论使用何种方式编译打包，我们最终需要生成一个 package.zip，它至少包含如下文件：
* icon.png
* index.js
* plugin.json
* preview.png
* README*.md
* index.css (optional)
* i18n/* (optional)
## 上架集市
* 执行 `pnpm run build` 生成 package.zip
* 在 GitHub 上创建一个新的发布，使用插件版本号作为 “Tag
version”，示例 https://github.com/siyuan-note/plugin-sample/releases
* 上传 package.zip 作为二进制附件
* 提交发布
如果是第一次发布版本，还需要创建一个 PR 到 [Community Bazaar](https://github.com/siyuan-note/bazaar) 社区集市仓库，修改该库的
plugins.json。该文件是所有社区插件库的索引，格式为：
```json
{
"repos": [
"username/reponame"
]
}
```
PR 被合并以后集市会通过 GitHub Actions 自动更新索引并部署。后续发布新版本插件时只需要按照上述步骤创建新的发布即可，不需要再
PR 社区集市仓库。
正常情况下，社区集市仓库每隔 1 小时会自动更新索引并部署，可在 https://github.com/siyuan-note/bazaar/actions 查看部署状态。
## 使用 Github action 自动发布
样例中自带了 github action，可以自动打包发布，请遵循以下操作：
1. 设置项目 `https://github.com/OWNER/REPO/settings/actions` 页面向下划到 **Workflow Permissions**，打开配置
![](asset/action.png)
2. 需要发布版本的时候，push 一个格式为 `v*` 的 tag，github 就会自动打包发布 release（包括 package.zip）
3. 默认使用保守策略进行 pre-release 发布，如果觉得没有必要，可以更改 release.yml 中的设置：
```yaml
- name: Release
uses: ncipollo/release-action@v1
with:
allowUpdates: true
artifactErrorsFailBuild: true
artifacts: 'package.zip'
token: ${{ secrets.GITHUB_TOKEN }}
prerelease: true # 把这个改为 false
```

4
plugin.json
View file

@ -12,8 +12,8 @@
"zh_CN": "使用 vite 和 svelte 开发的思源插件样例" "zh_CN": "使用 vite 和 svelte 开发的思源插件样例"
}, },
"readme": { "readme": {
"en_US": "README_en_US.md", "en_US": "README.md",
"zh_CN": "README.md" "zh_CN": "README_zh_CN.md"
}, },
"i18n": [ "i18n": [
"en_US", "en_US",